
Using NROFF and TROFF 





Part Number: 800-1755-10 
Revision A, of 9 May 1988 













UNIX is a registered trademark of AT&T. 

SunOS is a trademark of Sun Microsystems, Inc. 

Sun Woricstation is a registered trademaik of Sun Microsystems, Inc. 

Material in this manual comes from a number of sources: NrojfITrojf User’s 
Manual . Joseph F. Ossanna, Bell Laboratories, Murray Hill, New Jersey; A Troff 
Tutorial, Brian W. Kemighan, Bell Laboratories, Murray Hill, New Jersey; Typ¬ 
ing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff , 
M. E. Lesk, BeU Laboratories, Murray Hill, New Jersey; A Guide to Preparing 
Documents with -ms , M. E. Lesk, BeU Laboratories, Murray HiU, New Jersey; 
Document Formatting on UNIX Using the -ms Macros , Joel Kies, University of 
California, Berkeley, California; Writing Papers with Nroff Using -me, Eric P. 
AUman. University of California, Berkeley; and Introducing the UNIX System, 
Henry McGilton. Rachel Morgan, McGraw-HiU Book Company, 1983. These 
materials are gratefuUy acknowledged. 


Copyright © 1987,1988 by Sun Microsystems, Inc. 

This publication is protected by Federal Copyright Law, with aU rights reserved. 
No part of this publication may be reproduced, stored in a retrieval system, 
translated, transcribed, or transmitted, in any form, or by any means manual, 
electric, electronic, electro-magnetic, mechanical, chemical, optical, or other¬ 
wise, without prior explicit written permission from Sun Microsystems. 



Contents 


Chapter 1 Introduction.. 3 

1.1. nrof f and trof f. 3 

Text Formatting Versus Word Processing. 4 

The Evolution of nrof f and trof f.. 5 

Preprocessors and Postprocessors. 6 

1.2. troff. Typesetters, and Special-Purpose Formatters. 6 

1.3. Using the nrof f and troff Text Formatters. 6 

Options Common to nr of f and t rof f. 7 

Options Applicable Only to nrof f. 7 

Options Applicable Only to trof f. 8 

1.4. General Explanation of troff and nrof f Source Files. 8 

Backspacing. 9 

Comments. 9 

Continuation Lines. 10 

Transparent Throughput... 10 

Formatter and Device Resolution. 10 

Specifying Numerical Parameters... 10 

Nmnerical Expressions. 12 

1.5. Output and Error Messages....„... 13 

Chapter 2 Line Format......... 17 

2.1. Controlling Line Breaks. 18 

. br — Break Lines. 20 

Continuation Lines and Interrupted Text. 20 



























Contents — Continued 


rs, 

\ J 

2.2. Justifying Text and Filling Lines...... 21 

. ad — Specify Adjusting Styles. 21 

. na —No Adjusting... 22 

. nf aiMl . f i —Turn Filling Off and On. 23 

2.3. Hyphenation.. 24 

. nh and . hy — Control Hyphenation. 24 

. hw —• Specify Hyphenation Word List. 25 

. he — Specify Hyphenation Character. 26 

2.4. . ee — Center Lines of Text. 27 

2.5. . Till, and . cm — Underline or Emphasize Text. 28 

2.6. . uf — Underline Font. 29 


Chapter 3 Page Layout. 

3.1. Margins and Indentations. 

. po — Set Page Offset. 

. 11 — Set Line Length. 

. in — Set Indent. 

. t i — Temporarily Indent One Line. 

3.2. Page Lengths, Page Breaks, and Conditional Page Breaks 

. pi — Set Page Length. 

. bp — Start a New Page. 

. pn — Set Page Number. 

. ne — Specify Space Needed. 

3.3. Multi-Column Page Layout by Marking and Returning. 

. mk — Mark Current Vertical Position. 

. rt — Return to Marked Vertical Position. 


33 

35 

35 

35 



41 

41 

41 

42 

42 

43 

43 

44 


Chapter 4 Line Spacing and Character Sizes. 

4.1. . sp — Space Vertically. 

4.2. . ps — Change the Size of the Type. 

4.3. . vs — Change Vertical Distance Between Lines 

4.4. .Is — Change Line Spacing. 

4.5. \x Function — Get Extra Line-Space. 


47 

47 

48 

50 

51 

52 



- IV - 


































Contents — Continued 


4.6. .s v — SaveBloekof Vertical Space. 52 

4.7. . os — Ou^ut Saved Vertical Space. 53 

4.8. . ns — Set No Space Mode. 53 

4.9. . r s — Restore Space Mode. 53 

4.10. . s s — Set Size of Space Character. 54 

4.11. . e s — Set Constant-Widdi Characters. 54 

Chapters Fonts and Special Characters. 57 

5.1. .ft — Set Font. 58 

5.2. . f p— Set Font Position. 59 

5.3. . f z — Force Font Size. 59 

5.4. .bd — Artificial Boldface.. 60 

5.5. Character Set. 61 

5.6. Fonts... 62 

5.7. . Ig — Control Ligatures. 62 

Chapter 6 Tabs, Leaders, and Fields. 67 

6.1. . t a — Set Tabs. 67 

Setting Relative Tab Stops. 68 

Right-Adjusted Tab Stops. 68 

Centered Tab Stops. 68 

. t e — Change Tab Replacement Character. 69 

Summary of Tabs. 70 

6.2. Leaders — Repeated Runs of Characters. 71 

. Ic — Change ihe Leader Character. 73 

6.3. . f e — Set Field Characters... 74 

Chapter? Titles and Page Numbering. 81 

7.1. Titles in Page Headers. 81 

7.2. Fonts and Point Sizes in Titles. 83 

7.3. . pc — Page Number Character. 84 

7.4. . 11 Request—Three Parameters.. 85 


Chapter 8 trof f Input and Output 


89 

































Contents — Continued 


8.1. .so—Read Text from a File. 89 

8.2. . nx — Read Next Source File. 91 

8.3. Pipe Output to a Specified Program (nroff only). 91 

8.4. .rd—Read from the Standard Input. 92 

8.5. . ex — Exit from nroff or trof f. 94 

8 . 6 . . tm — Send Messages to the Standard Error File. 94 

Chapter 9 Strings... 97 

9.1. . ds — Define Strings. 98 

9 . 2 . .as — Append to a String. 99 

9.3. Removing or Renaming String Definitions. 101 

Chapter 10 Macros, Diversions, and Traps. 105 

10.1. Macros. 105 

. de — Define a Macro. 105 

. rm — Remove Requests, Macros, or Strings. 107 

. r n — Rename Requests, Macros or Strings. 108 

Macros With Arguments. 108 

. am — Append to a Macro... 112 

Copy Mode Input Interpretation. 112 

10.2. Using Diversions to Store Text for Later Processing. 112 

. di — Divert Text. 113 

. da — Append to a Diversion. 114 

10.3. Using Traps to Process Text at Specific Places on a Page. 1 14 

. wh — Set Page or Position Traps. 115 

. ch — Change Position of a Page Trap. 115 

. dt — Set a Diversion Trap. II 5 

. i t — Set an Input-Line Count Trap. 115 

. em — Set the End of Processing Trap. 117 

Chapter 11 Number Registers. 121 

11 . 1 . . nr — Set Number Registers. 12 i 

11 . 2 . Auto-Increment Number Registers. 123 

































Contents — Continued 


11.3. Arithmetic Expressions with Number Registers. 124 

11.4. .af — Specify Format of Number Registers. 125 

11.5. . rr — Remove Number Registers. 127 

Chapter 12 Drawing Lines and Characters. 131 

12.1. \u and \d Functions — Half-Line Vertical Movements. 131 

12.2. Arbitrary Local Horizontal and Vertical Motions. 132 

\ V Function — Arbitrary Vertical Motion. 132 

\h Function — Arbitrary Horizontal Motion. 133 

12.3. \ Q Function — Digit-Size Spaces. 134 

12.4. ‘ \ ’ Function — Unpaddable Space. 136 

12.5. \ | and \ " Functions — Thick and Thin Spaces. 136 

12.6. \ & Function — Non-Printing Zero-Width Character. 137 

12.7. \ o Function — Overstriking Characters. 138 

12.8. \ z Function — Zero Motion Characters. 139 

12.9. \ w Function — Get Width of a String. 140 

12.10. \ k Function — Mark Current Horizontal Place. 141 

12.11. \b Function — Build Large Brackets. 142 

12.12. \ r Function — Reverse Vertical Motions. 143 

12.13. Drawing Horizontal and Vertical Lines. 143 

\ 1 Function — Draw Horizontal Lines. 143 

\ L Function — Draw Vertical Lines. 144 

Combining the Horizontal and Vertical Line Drawing 

Fimctions. 145 

12.14. . me—Place Characters in the Margin. 145 

Chapter 13 Character Translations. 149 

13.1. Input Character Translations. 149 

13.2. .ecand.eo — Set Escape Character or Stop Escapes. 149 

13.3. . cc and . e2 — Set Control Characters .....;. 150 

13.4. . tr — Output Translation. 150 

Chapter 14 Automatic Line Numbering.. 153 

14.1. .nm — Number Output Lines. 153 

































Contents — Continued 


14.2. , nn — Stop Numbering Lines. I 54 

Chapter 15 Conditional Requests. I 57 

15.1. .if — Conditional Request. I 57 

15.2. . ie and . el — If-Else and Else Conditionals. 160 

15.3. .ig — Ignore Input Text. 160 

Chapter 16 Debugging Requests. 165 

16.1. . pm — Display Names and Sizes of Defined Macros. 165 

16.2. . f 1 — Flush Output Buffer. 166 

16.3. .ab—Abort. 166 

Chapter 17 Environments... 169 

17.1. . ev — Switch Environment. 169 

Appendix A t r o f f Request Summary. I 73 

Appendix B Font and Character Examples. 181 

B.l. Font Style Examples. 181 

B.2. Non-ASCH Characters and minus on the Standard Fonts. 182 

B.3. Non-Ascn Characters and , G, +, —, =, and * on the Special 

Pont. 182 

Appendix C Escape Sequences. 187 

Appendix D Predefined Number Registers. 191 

Appendix E troff Output Codes. I 95 

E. 1 . Codes OOxxxxxx — Flash Codes to Expose Characters. 196 

E. 2 . Codes Ixxxxxxx — Escape Codes Specifying Horizontal 

Motion. 

E.3. Codes 01 Ixaxc — Lead Codes Specifying Vertical Motion. I 97 

E.4. Codes 010 Ixxxx — Size Change Codes. I 97 

E.5. Codes 0 l O Oxxxx — Control Codes. 198 

E. 6 . How Fonts are Selected. I 99 


~ viii - 




























Contents — Condnmd 



E.7. Initial State of the C/A/T. 199 

Index. 201 




— IX- 






Tables 


Table 1-1 Scale Indicators for Numerical Input. 11 

Table 1-2 Default Scale Indicators for Certain t rof f Requests and 

Functions. 11 

Table 1-3 Arithmetic Operators and Logical Operators for Expressions. 12 

Table 2-1 Constructs that Break the Filling Process. 19 

Table 2-2 Formatter Requests that Cause a Line Break. 20 

Table 2-3 Adjusting Styles for Filled Text. 21 

Table 5-1 Exceptions to the Standard ASCn Character Mapping. 62 

Table 6-1 Types of Tab Stops. 70 

Table 7-1 Requests that Cause a Line Break. 83 

Table 11-1 Access Sequences for Auto-incrementing Number 

Registers... 124 

Table 11-2 Arithmetic Operators and Logical Operators for 

Expressions. 124 

Table 11-3 Interpolation Formats for Number Registers.... 126 

Table 12-1 trof f WiddiFunction — et Number Register Values- 141 

Table 12-2 Pieces for Constructing Large Brackets . 142 

Table 15-1 Built-In Condition Names for Conditional Processing .... 159 



















Tables — Continued 


o 

Table A -1 Summary of nrof f and trof f Requests. 173 

Table A -2 Notes in the Tables. 17g 

Table B -1 Summary of trof f Special Qiaraoters. 182 

Table C -1 trof f Escape Sequences. Igy 

Table D -1 General Number Registers. 191 

Table D -2 Read-Only Number Registers. 191 

Table E -1 Size Change Codes. 197 

Table E -2 Single Point-Sizes versus Double Point-Sizes. 198 

Table E -3 C/A/T Control Codes and their Meanings. 198 

Table E -4 Correspondence Between Rail, Mag, Tilt, and Font Number. 199 












Figures 

i 


Figure 2-1 Filing and Adjusting Styles.i 22 

Figure 3-1 Layout of a Page.i 34 








o 




Preface 



Summary of Contents 



This manual provides reference information and examples for the text formatters 
nrof f and trof f. We assume you are familiar with a terminal keyboard and 
the Sun system. If you are not, see Getting Started with SunOS: Beginner’s 
Gw/rfe for information on the basics, like logging in and the Sun ffle system. If 
you are not familiar with text editors, read Doing More wit/i SunOS: Beginner’s 
Guide and the chapter “Introduction to Text Editing” in Editing Text Files. 
Finally, we assume that you are using a Sun Workstation, although specific ter¬ 
minal information is also provided. 

For additional details on Sun system commands and programs, see the SunOS 
Reference Manual. 

Here is a summary of the chapters that foUow: 

1. Introduction — Describes what trof f can do for you, some tools you can 
use with trof f or nrof f to refine your results, how to use nrof f and 

t rof f, the differences between the two text formatting programs, and a lit¬ 
tle about the mechanisms built-in to nrof f and trof f. 

2. Line Format —Explains how the text formatting programs fill and adjust 
text input lines and how various formatting requests affect filling and adjust¬ 
ing functions in t rof f. 

3. Page Layout — Describes the default page layout parameters built-in to 

t rof f and how you can alter them. Also explains how certain formatting 
requests interact in laying out pages. 

4. Line Spacing and Character Sizes — Explains the available type and spac¬ 
ing sizes in trof f and nrof f, and how to change them. 

5. Fonts and Special Characters — Describes the fonts available with nr of f 
and trof f and how to change tiiem. 

6 . Tabs, Leaders, and Fields — Explains what tabs, leaders, and fields are, and 
how to set them. 

7. Titles and Page Numbering — Explains how to create page h|?|#rs and 
page footers. Also covers how to use the built-in troff page number regis¬ 
ter to print page numbers on your document automatically. 


-XV - 
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Conventions Used in This 
Manual 


8 . t r o f f Input and Output — Describes how to embed files within files, to 
switch input from one file to another, to display a message on your terminal 
whentroff reaches a certain point in a file, and in nroff only, how to 
pipe the output ftom a file to a program by using a special nroff command 
in the file. 


9. Strings —Explains how to give a string of characters a new name so you 
can reference them easily. Also provides a facility for referencing the values 
of the strings. 

10 . Macros, Diversions, and Traps — Describes how to define macros, store 
information in diversions, and use diversions and traps to process text at 
specific places on pages. 

11. Number Registers — Explains what tr of f number registers are and what 
you can use their values for. 

12. Drawing Lines and Characters — Describes the several built-in trof f 
functions for moving to arbitrary places on the page and for drawing things. 

13. CharacterTranslations — Describes how to change the escape character 
and translate the value of one character into another. 


14. Automatic Line Numbering — Explains how to use the t rof f requests for 
numbering lines in the output file. 

15. Conditional Requests — Describes t r of f mechanisms for conditionally 
accepting input. 



16. Debugging Requests — Explains requests for displaying names and sizes of 
defined macros, flushing the output buffer, and aborting the formatting. 

17. Environments — Describes how to shift input processing between the three 
nroff/troff environments. 

A. trof f Request Summary — A quick reference summarizing nroff and 
troff requests. 


B. Font and Character Examples — Several tables of special characters like 
Greek letters, foreign punctuation, and math symbols. 

C. Escape Sequences — Summarizes escape sequences for obtaining values of 
number registers, for describing arbitrary motions and drawing things, and 
for specifying certain miscellaneous functions. 

D. Predefined Number Registers — Tables, of tcott General and Predefined 
Number Registers 

E. troff Output Codes — A summary of the binary codes for the C/A/T pho¬ 
totypesetter. 


Throughout this manud we use 


/---— 

hostname% 


L 

---- 
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Notation Used in This Manual 


as the prompt to which you type system commands. Boldface type¬ 
writer font indicates commands that you type in exactly as printed on the 
page of this manual. Regular typewriter font represents what the sys¬ 
tem prints out to your screen. Typewriter font also specifies Sun system com¬ 
mand names (program names) and illustrates source code listings. Italics indi^ 
cates general arguments or parameters that you should replace with a specific 
word or string. We also occasionally use italics to emphasize important terms. 

Numerical parameters are indicated in this manual in two ways. ±N means that 
the argument may take the forms N, -tN, or -N and that the corresponding effect 
is to set the affected parameter to N, to increment it by N, or to decrement it by N 
respectively. Plain N means that an initial algebraic sign is not an increment 
indicator, but merely the sign of N. Generally, unreasonable numerical input is 
either ignored or truncated to a reasonable value. For example, most requests 
expect to set parameters to non-negative values; exceptions are .sp, .wh, .ch, 
.nr, and .if. The requests .ps, .ft, .po, .vs, .Is, .11, .in, and .It 
restore the prcvioits parameter value in the absence of m argument. 

Single-character arguments are indicated by single lower case letters and one- or 
two-character arguments are indicated by a pair of lower case letters. Character 
string arguments are indicated by multi-character mnemonics. 
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Introduction 


1.1. n r o f f and t r o f f nr o f f and t ro f f are text processing utilities for the Sun system, nr of f for¬ 

mats text for typewriter-like terminals (such as Diablo printers), trof f is 
specifically oriented to formatting text for a phototypesetter, nroff and trof f 
accept lines of text (to be printed on the final output device) interspersed with 
lines of fonnat control information (to specify how tiie text is to be laid out on 
the page) and format die text into a printable, paginated document having a user- 
designed style, nroff and trof f offer unusual freedom in document styling, 
including: 

o detailed control over page layout; 

□ arbitrary style headers and footers; 

□ arbitrary style footnotes; 

□ automatic sequence numbering for pju^graphs, sections, ett:; 
o multiple-column output; 

□ dynamic font and point^size control; 

□ arbitrary horizontal and vertical local motions at any point; 

□ a family of automatic overstriking, bracket construction, and line drawing 
functions. 

nroff and troff are highly compatible with each other and it is almost 
always possible to prepare input acceptable to both. The formatters provide 
requests (conditional input) so that you can embed input expressly destined for 
either nroff or troff. nroff can prepare output directly for a variety of ter¬ 
minal types and is capable of utilizing the fuU resolution of each terminal. 

This manual provides a user’s guide and reference section for nr of f and 
troff. Note that throughout the text we refer to nroff and troff more or 
less interchangeably — places where the narrative refers specifically to one or the 
other processor are noted.^ 

You should be aware that using nroff or troff ‘in the raw’ requires a 
detailed knowledge of tiie way that these programs woric and a certain knowledge 


^ The material in this chapter ^volvod from A troff Tutorial^ by Brian Kemighan of Belli Laboratories* and 
from nroffftroff User’s Manualy originally written by Joseph Ossanna of Belli Laboratories. 



microsystems 


) 


3 


Revision A, of 9 May 1988 




4 Using nroff and trof f 


oftypographical terms, nrof f and troff don’t do agreat deal of woik for you 
— for example, you have to explicitly teU them how to indent paragraphs and 
number pages and things like that. 

If what you are trying to do is just get a job done (like writing a memo), you 
shouldn’t be reading this manual at all, but rather the chapter “Formatting Docu¬ 
ments with the -ms Macros” in the Formatting Documents manual. If, on the 
other hand, you would like to learn the fine details of a progr ammin g language 
designed to control a typesetter, this is the place to start reading. 

hi many ways, nrof f ’s and trof f’s control language resembles an assembly 
language for a computer — a remarkably powerful and flexible one — many 
operations must be specified at a level of detail and in a form that is too hard for 
most people to use effectively. 

The single most important rule when using trof f is not to use it directly, but 
through some intermediary such as one of the macro packages, or one of the vari¬ 
ous preprocessors described in Formatting Documents. In the few cases where 
existing macro packages don’ t do the whole job, the solution is not to write an 
entirely new set of troff instructions from scratch, but to make small changes 
to adapt existing packages. In accordance with this strategy of letting someone 
else do the woric, the part of trof f described here is only a small part of the 
whole, although it tries to concentrate on the more useful parts. In any case, 
there is no attempt to be complete. Rather, the emphasis is on showing how to 
do simple things, and how to make incremental changes to what already exists. 

If you are interested in the complete story, look into the troff source itself 

Text Formatting Versus Word Many newcomers to the UNIX system are surprised to find that there are no word 

Processing processors available. This is largely historical — the types of documents (such 

as the Sun manuals) that people do with the UNIX system’s text formatting pack¬ 
ages just can’t be done with existing word processors. Before you get into the 
details of nroff and troff, here is a short discussion on the differences 
between text formatters and word processors, and their relative strengths and 
weaknesses. 

A word processor is a program that to some extent simulates a typewriter—text 
is edited and formatted by one program. You type text at a computer terminal, 
and the word processor formats the text on the screen for you as you go. You 
usually get special effects like underlining and boldface by typing control indica¬ 
tors. The word processor usually displays these activated features using inverse 
video or special marks on the screen. The document is displayed on the terminal 
screen in the same format as it will appear on the printing device. The effects of 
this are often termed ‘What You See Is What You Get’ (usually called 
WYSIWYG and pronounced ‘ wizzi-wig’). Unfortunately, as has been pointed 
out, the problem with many WYSIWYG editors is that ‘What You See Is All You 
Get’. In general, word processors cannot handle large documents. In principle, it 
is possible to write large manuals and even whole books with word processors, 
but the process gets painful for large manuscripts. Sometimes a change, such as 
deleting a sentence or inserting a new one, in the early part of a document can 
require that the whole document has to be reformatted. A change in the overall 
structure of the formatting requirements (for example, a changed indentation 
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depth) will also mean diat the whole document has to be refonnatted. Word pro¬ 
cessors usually don’t cope widi automatic chapter and section munbering (of the 
kind you see in the Sun manuals), neither can they generate tables of contents 
and indices automatically. These tasks have to be done manually, and are a 
potential source of error. Word processors are eminently suitable for memos and 
letters, and can handle short documents. But large documents, or formatting 
documents for sophisticated devices like modem phototypesetters, requires a text 
formatter. 

A text formatter such as nrof f or trof f does not in general perform any edit¬ 
ing — its only job is reading text from a file and formatting that text for printing 
on some device. Entering the text into the file, and formatting the text from that 
file for printing are two separate and independent operations. You prepare your 
file of text using a text editor such as vi (described elsewhere in this manual); 
The file contains text to be formatted, interspersed with formatting instructions 
which control the layout of the final text. The text formatter reads this file of 
text, and obeys the formatting instmctions contained in the file. The results of 
the formatting process is a finished document The disadvantage of a text for¬ 
matter is that you have to run them to find out what tire final result will look like. 
Many people find the idea of embedded ‘formatting commands’ foreign, as tiiey 
do the idea of two separate processes (an edit followed by a run of the formatter) 
to get the final document 

Notwithstanding all of the above, the UNIX system has had text formatting utili¬ 
ties since the very beginning, and many documents were written using the capa¬ 
bilities of nrof f or trof f. 


The Evolution of nrof f and One of the very first text formatting programs was called runo#and was a utility 

trof f for the Compatible Time Sharing System (CTSS) atMIT in the early 1960’s. 

was named for the way that people would say ‘I’U just run off a docu¬ 
ment’. 

When the UNIX system came to have a text formatter, the text formatter was 
called roj^, because UNIX people like to call things by short and cryptic names. 
Roffwas a. simple program that was easy to woik with as long as you were writ¬ 
ing very small and simple documents for a line-printer. In some ways, roff is 
easier to use tiian nr o f f or t r o f f because roffh&d built-in facilities such as 
being able to specify running headers and footers for a document with simple 
commands. 

nroff stands for‘Newer rojf’. troff is an adaptation of nrof f todrivea 
phototypesetting machine. Although troff is supposed to mean ‘typesetter 
roff, some people have formed the theory that troff actually stands for ‘Times 
Romanofr because of trof f’s penchant for the Times Roman typeface. 

nrof f and t roff are much more flexible (and much more complicated) pro¬ 
grams— it’s safe to say that they don’t do a lot for you — for instance, you have 
to manage your own pagination, headers, and footers. The way that nroff and 
troff ease tiie burden is via facilities to define your own text formatting com¬ 
mands (macros), define strings, and store and manipulate numbers. Without 
these facilities, you would go mad (many people have — the author of this 
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document among them). In addition, there are supporting packages for doing 
special effects such as mathematics and tabular layouts. 


Because trof f or nrof f are so hard to use ‘in the raw’, various tools have 
evolved to convert from human-oriented ways of specifying things into codes 
that trof f or nrof f can understand. Tools that do translations for trof f or 
nr of f before the fact are called preprocessors. There are also tools that hack 
over the output of nrof f for different devices or for other requirements. Tools 
that do conversions of t rof f or nrof f output after the fact are called 
cessors. Refer to the manual Formatting Documents for explanations of nr of f 
and trof f pre- and postprocessors. 

Please be sure to reat/ t/iw : this section covers some aspects of trof f that 
are generally glossed over in the traditional UNIX system manuals, trof f was 
originally designed as a text formatter targeted to one specific machine — that 
machine was called a Graphics Systems Incorporated (GSI) C/A/T (Computer 
Assisted Typesetter). The C/A/T is a strange and wonderful device with strips of 
film mounted on a revolving drum, lenses, and light pipes. The C/A/T flashes 
character images on film which you then develop to produce page proofs for your 
book or manual or whatever. The C/A/T is almost extinct now except for some 
odd niches like Beikeley. 

trof f was written very much with the C/A/T in mind. The internal units of 
measurement that trof f uses are C/A/T units, t rof f only understands four 
fonts at a time, and so on. Throughout this chapter, much of the terminology is 
based on trof f’s intimate relationship with the C/A/T. 

To use nrof f or trof f you first prepare your file of text with nrof f or 
trof f requests embedded in the file to control the formatting actions. The 
remainder of this document discusses the formatting commands. Then you ran 
the formatter at the command level like this: 


. - 

hoStname% 

V 

nroff options files 


or, of course: 

hostname % 

troff options files 

_> 


where options represents any of a number of option arguments and files 
represents the list of files containing the document to be formatted. 


An argument consisting of a single minus (-) is taken to be a file name 
corresponding to the standard input. If no file names are given, input is taken 
from the standard input. 

Options may appear in any order so long as they appear before the files. There 
are three parts to the list of options below: the first list of options are common to 
both nrof f and t rof f; the second list of options are only applicable to 
nroff; the third list of options are only applicable to troff. 


1.3. Using the nroff and 
troff Text 
Formatters 


1.2. t ro f f, Typesetters, 
and Special-Purpose 
Formatters 


Preprocessors and 
Postprocessors 
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Each option is typed as a separate argument — for example, 

--- : --- ^ 

hostname% nroff -o4,8-10 -T300S -ms filel file2 

s___^ 

formats pages 4, 8,9, and 10 of a document contained in the fdes named filel and 
file2, specifies the ou^ut terminal as a DASI-300S, and invokes the -msun macro 
package. 


Options Common to nroff 
and troff 


-olist 

Print only pages whose page numbers appear in list, which consists of 
comma-separated numbers and number ranges. A number range has the 
form A-M and means pagesJV through M; an initial -N means from the 
beginning to page N; and a final N- means from N lo the end. 

-tiN 

Number first generated page N. 

-sN 

Stop every N pages, nroff will halt prior to every N pages (default N=\) 
to ttfiow paper loading or changing, and will resume upon receipt of a new- 
line. 


-taname 

Adds the macro file /usr/lib/tmac/tmac . name before the inputJ^Zes. 

-raN 

Register a (one-character) is set to N. 

-i Read standard input after the input files are exhausted. 

-q Invoke the simultaneous input-output mode of the . r d request. 

-z Suppress formatted output. The only output you get are messages from . tm 
(terminal message) requests, and from diagnostics. 


Options Applicable Only to 

nroff 


-h Output tabs used during horizontal spacing to speed output as well as reduce 
byte count. Device tab settings assumed to be every 8 nominal character 
widths. Default settings of input (logical) tabs is also initialized to every 8 
nominal character widths. 


-Tname 

Specifies the name of the output terminal type. Currently-defined names are 
37 for the (default) Model 37 Teletype® , tnSOO for the GE TermiNet 300 
(or any terminal without half-line capabilities), 30 O S for the DASI-300S, 
300 for the DASl-300, and 4 5 0 for tiie DASi-450 (Diablo Hyterm). 

-e Produce equally-spaced words in adjusted lines, using full terminal resolu¬ 
tion. 


wsun 

Xr microsystems 
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Options Applicable Only to -t Direct output to the standard output instead of the phototypesetter. 

trof f 

-a Send a pnntable (ASCIf) approximation of the results to the standard output. 
-pN 

Print all characters in point size N while retaining aU prescribed spacings 
and motions, to reduce phototj^setter elapsed time. 


1.4. General Explanation 

of trof f and nrof f 

Source Files 


This section of the nr o f f and t r o f f manual covers generic topics related to 
the format of the input file, how requests are formed, and how numeric parame¬ 
ters to requests are stated. 

To use tr of f, you have to prepare not only the actual text you want printed, but 
some information that tells how you want it printed. For t r o f f, the text and the 
formatting information are often intertwined. Most co mmands to tr of f are 
placed on a line separate from the text itself, beginning with a period (one com¬ 
mand per line). For example: 


Here is some text in the regular size characters, 
but we want to make some of the text in a 
.ps 14 

larger size to emphasize something 


changes the ‘pomt size’, that is, the size of the letters being printed, to ‘14 point’ 
(one point is 1/72 inch) like this: 

Here is some text in the regular size characters, but we want to make some of the 
text in a larger size to emphasize something 


Occasionally, though, something special occurs in the middle of a line —to 
produce Area=7ir^ you have to type 


r --- 

Area = \(*p\fIr\fR^ 

1 \a8\u2\d\s0 






(which we will explain shortly). The backslash character (\) introduces trof f 
commands and special characters within a line of text. 


To state the above more formally, an input file to be processed by trof f or 
nrof f consists of text lines, which are destined to be printed, interspersed with 
control lines, which set parameters or otherwise control subsequent processing. 

A control line is usually called a request. 

A request begins with a control c/iarocfer—normally . (period) or ' (apos¬ 
trophe or acute accent) — followed by a one or two character name. A request is 
either: 

a basic request 

(also called a command) which is one of the many predefined things that 
nro f f or t ro f f can do. For example, .11 6.5 i is a basic request to set 
the line-length to 6.5 inches, and . i n 5 is a basic request to indent the left 
margin by five en-spaces. 
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Backspacing 


Comments 


a macro reference 

sp>ecifles substitution of a user-defined macro in place of the request. A 
macro is a predefined collection of basic requests and (possibly! ofiier mac¬ 
ros. For example, in the -ms macro package discussed elsewhere in this 
manual, . lp is a macro to start a new left-blocked paragraph. 

The ' (apostrophe or acute accent) control character suppresses file break 
function— the forced output of a partially filled line— caused by certain 
requests. 

The control character may be separated from the request or macro name by white 
space (spaces and/or tabs) for aesthetic reasons. Names must be followed by 
either space or newline, nroff ortroff ignores control lines whose names 
are unrecognized. 

Various special functions may be introduced any where in the input by means of 
an escape character, normally \. For example, the function \nR interpolates the 
contents of the number register whose name is R in place of the function. Here R 
is either a single character name in which case the escape sequence has the form 
Vruc, or else7? is a two-character name, in which case the escape sequence must 
have the form \ n (xc. In general, there are many escape sequences whose one- 
character form is \ fx and whose two-character form is \f (xc, where f is the 
function and x or xc is the name. 

To print file escape character (usually backslash), use \e (backslash e). 

Unless in copy mode, \hc ASCII backspace character is replaced by a backward 
horizontal motion having the width of the space character. Underlining as a form 
of line-drawing is discussed in file section on Arbitrary Motions and Drawing 
Lines and Characters. A generalized overstriking function is also described in 
the above- mentioned section. 


Comments may be placed at the end of any line by prefacing them with \ ”. A 
comment line cannot be continued by placing a \ at the end of the line — see the 
discussion on continuation lines below. 

A line beginning with \ " appears as a blank line and behaves like a . sp 1 
request: 




Here is a line of text. 

\” Here is a comment on a line by itself. 


Here is another line of text. 

._____ 

. J 

when we format the above lines we get this: 

r 

Here is a line of text. 


Here is another line of text. 


L____ 

J 


If you want a comment on a line by itself but you don’t want it to appear as a 
blank line, type it as . \ 
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Continuation Lines 


Transparent Throughput 


Formatter and Device 
Resolution 


Specifying Numerical 
Parameters 


/--- - — - 

Here is a line of testt 

.\" and here is a Gorament on a line by itself 
and here is another line of text 


N 

when we format the above lines we get this: 

Here is a line of text 


A 

and here is another line of text 





_ / 


An uncomfortably long input line that must stay one line (for example, a string 
definition, or unfilled text) can be split into many physical lines by ending all but 
the last one with the escape \. The sequence \ (newline) is always ignored — 
except in a comment — see below. This provides a continuation line facility. 
TheX at the end of the line is called concealed newline in the jargon. 

An input line beginmng with a \ ! is read in copy mode and transparently output 
(without the initial \!); the text processor is otherwise unaware of the line’s 
presence. This mechamsm may be used to pass control information to a post¬ 
processor or to embed control lines in a macro created by a diversion. Refer to 
Chapter 10 for information describing diversions. 

trof f internally uses 432 units^nch, corresponding to the phototypesetter 
which has a horizontal resolution of 1/432 inch and a vertical resolution of 1/144 
inch, nrof f internally uses 240 units/inch, corresponding to the least common 
multiple of the horizontal and vertical resolutions of various typewriter-like out¬ 
put devices, trof f rounds horizontal/veitical numerical parameter input to the 
actual horizontal/vertical resolution of the Graphic Systems typesetter, nrof f 
similarly rounds numerical input to the actual resolution of the output device 
indicated by the -T option (default Model 37 Teletype). 

Many requests can have numerical arguments. Both nrof f and trof f accept 

numerical input in a variety of units. The general form of such input is 
/-----—-—_____ 

.XX nnnn units 

V___ 

--------- V 

where .rx is the request, nnnn is the number, and units is the ’’scale indicator.” 

Scale indicators are shown in the foHowing table, where S is the current type size 
in points, V is the current vertical line spacing in basic units, and C is a nominal 
character width in basic units. 
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Table 1-1 Scale Indicators for Numerical Input 


Scale 
\ Indicator 

Meaning 

Number of basic units 
troff nroff 

i 

Inch 

432 

240 

c 

Centimeter 

432x50/127 

240x50/127 

P 

Rea = 1/6 inch 

72 

240/6 

ni: 

Em = S points 

6xS 

C 

n 

En = En^ 

3xS 

; C, same as Em 


Point = 1/72 inch 

6 

240/72 


Basic unit 

1 

: 1 

V 

Vertical line space 

V 

: V 

none 

; Default, see below 




In nroff, 6or/t the em and the en are taken to be equal to the C, which is 
output-device dependent; common values are 1/10 and 1/12 inch. Actual charac¬ 
ter widths in nrof f need not be all the same and constmeted characters such as 
-> (->) are often extra-wide. 

The default scaling is ems for the horizontally-oriented requests and fimetions, 

Vs for the vertically-oriented requests and functions, p for tiie vertical spacing 
request; and u for the number register and conditional requests. See Table 1-2 for 
a summary of the default scale indicators for the troff requests and functions 
that take scale indicators. 

Table 1-2 Default Scale Indicators for Certain troff Requests and Functions 


Request 

Default Sealing Unit 

Request 

Default Sealing Unit 

\ .11 

ems 

.pi 

vertical units (Vs) 

.in 

tf 

. wh 

Hi 

.ti 

tii 

. ch 

H 

• ta 

If 

.dt 

H 

.It 

tr 

. sp 

H 

; ‘PO 

It 

. sv 

Hi 

^ .me 

It 

. ne 

H 

\h 

Hi 

.rt 

H 

1 VI 

Hi 

1 \v 

Hi 

.nr 

machine units (u) 

\x 

tr 

.if 

H 

1 \L 

H 

.ie 

H 

. vs 

picas (p) 


All other requests ignore any scale indicators. When a number register contain¬ 
ing an already appropriately-scaled number is interpolated to provide numerical 
input, the unit scale indicator u may need to be appended to prevent an additional 
inappropriate default sealing. The number, W, may be specified in decimal form, 
but the parameter finally stored is rounded to an integer number of basic units. 
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The absolute position indicator | (the pipe character) may precede a number AT to 
generate the absolute distance to the vertical or horizontal place N. For 
vertically-oriented requests and functions, I N becomes the absolute distance in 
basic units from the current vertical place on the page or in a diversion (see 
Chapter 10 for the section on diversions) to the vertical place N. For a// other 
requests and functions, | N becomes the distance from the current horizontal 
place on the input line to the horizontal place N. For example. 


— 

.sp 

3.2 c 


V 


-—_/ 


will space in the required direction to 3.2 centimeters from the top of the page. 


Numerical Expressions Wherever numerical input is expected, you can type an arithmetic expression. 

An expression involves parentheses and the arithmetic operators and logical 
operators shown in the table below: 

Table 1 -3 Arithmetic Operators and Logical Operators for Expressions 


Arithmetic Operator 

Meaning 

+ 

Addition 

- 

Subtraction 

/ 

Division 


Multiplication 

% 

Modulo 

Logical Operator 

Meaning 

< 

Less than 

> 

Greater than 

<= 

Less than or equal to 

>= 

Greater than or equal to 

= or== 

Equal to 

& 

and 

• 

or 


Except where controlled by parentheses, evaluation of expressions is left-to-right 
— there is no operator precedence. 

In certain requests, an initial + or — is stripped and interpreted as an increment or 
decrement indicator respectively. In the presence of default scaling, the desired 
scale indicator must be attached to every number in an expression for which the 
desired and default scaling differ. For example, if the number register x contains 
2 and the current point size is 10, then 


f -—-—----- 

.11 (4.25i+\nxP+3)/2u 



-—_- V 


will set the line length to \H the sum of 4.25 inches + 2 picas + 30 points. 


A 
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1.5. Output and Error The ou^ut from . tm, , pm^ and the prompt from . rd, as well as various error 

Messages messages are written onto the standard error message output. The latter is dif¬ 

ferent from the standard output, where nrof f formatted output goes. By 
default, both are written onto the user’s terminal, but they can be independently 
redirected — in the case of trof f, the standard output should always be 
redirected unless the -a option is in effect, because trof f’s output is a strange 
binary format destined to drive a typesetter. 

Various error conditions may occur during the operation of nrof f and t rof f. 
Certain less serious errors having only local impact do not stop processing. Two 
examples are word overflow, cmseA by a word that is too large to fit into the 
word buffer (in fiU mode), and line overflow, caused by an output line fiiat grew 
too large to fit in the line buffer; in both cases, a message is printed, the offend¬ 
ing excess is discarded, and the affected word or line is marked at the point of 
truncation with a * in nrof f and a <= in trof f. The philosophy is to continue 
processing, if possible, on the groimds that output useful for debugging may be 
produced. If a serious error occurs, processing terminates, and an appropriate 
message is printed. Examples are the inability to create, read, or write files, and 
the exceeding of certain internal limits that make future ou^ut unlikely to be 
useful. 
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Line Format 


Perhaps the most important reason for using t ro f f or nr o f f is to use its filling 
and adjusting capabilities. Here is what filling and adjusting mean: 

Filling means tiiat trof f or nrof f collects words from your input text 

lines and assembles the collected words into an output text line until 
some word doesn’t fit An attempt is then made to hyphenate the 
word in an effort to assemble a part of it into the output line. Filling 
continues until something happens to break the filling process, such 
as a blank line in the text, or one of the trof f ornroff requests 
that break the line — things that break the filling process are dis¬ 
cussed later on. 

Adjusting means that once the line has been filled as full as possible, spaces 

between words on the output line are then increased to spread out the 
line to the current line-length minus any current indent The para¬ 
graphs you have just been reading are both filled and adjusted. 
Justification implies filling — it makes no sense to adjust lines 
without also filling them. 

In the absence of any other information, trof f’s or nrof f’s standard behavior 
is to fill lines and adjust for strai^t left and right margins, so it is quite possible 
to create a neatly formatted document which only contains lines of text and no 
formatting requests. Given this as a starting point, the simplest document of all 
contains nothing but blocks of text separated by blank lines — trof f or nrof f 
will fill and justify those blocks of text into paragraphs for you. To get further 
control over the layout of text, you have to use requests and functions embedded 
in the text, and that is the subject of this entire paper on using trof f. 

A word is any string of characters delimited by the space character or file begin¬ 
ning or end of the input line. Any adj acent pair of words that must be kept 
together (neither split across ou^ut lines nor spread apart in the adjustment pro¬ 
cess) can be tied together by separating them with the unpaddable space charm- 
ter ‘ \ ’ (backslash-space) — also called a ‘hard blank’ in other systems. The 

adjusted word spacings are uniform in trof f and the minimum interword spac¬ 
ing can be controlled witii the . ss (space size) request. In nrof f, interword 
spaces are normally nonuniform because of quantization to character-size spaces, 
but the -e command line option requests uniform spacing to the full resolution 
of the output device. Multiple inter-word space characters found in the input are 
retained, except for trailing spaces. 
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o 

Riling and adjusting and hyphenation can all be prevented or controlled by 
requests that are discussed later in this part of the manual. 

An input text line ending with ., ?, or ! is taken to be the end of di sentence, and 
an additional space character is automatically provided during fillin g 

A text input line that happens to begin with a control character can be made to 
not look like a control line by prefacing it with the non-printing, zero-width filler 
character \ &. StiU another way is to specify output translation of some con¬ 
venient character into the control character using the . t r (translate) request— 
see the relevant section. 

The text length on the last line ouq)ut is available in the . n number register, and 
text baseline position on the page for this line is in the nl number register. The 
text baseline high-water mark on the current page is in the . h number register. 

2.1. Controlling Line When filling is turned on, words of text are taken from input lines and placed on 

Breaks output lines to make the output lines as long as they can be without overflowing 

the line length, until something happens to break the filling process. When a 
break occurs, the current output line is printed just as it is, and a new output line 
is started for the following input text. There are various things that cause a break 
to occur; 
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Table 2-1 

Constructs that Break the Filling Process 

Construct 

Explanation 

Blank linens) 

If your input text contains any completely blank lines, troff or nroff 
assumes you mean them. So it prints the current output line, flien your blank 
lines, then starts the following text on a new line. 

Spaces 

at the beginning of a line are significant. If there are spaces at the start of a 
line, troff or nroff assumes you know what you are doing and fiiat you 
reaUy want spaces there. Obviously, to achieve this, the current output line 
must be printed and a new line begun. Avoid using tabs for this purpose, 
since they do not cause a break. 

A .br request 

A . br request (break) request can be used to make sure that the following 
text is started on a new line. 

troff or nroff request 

Some troff or nroff requests cause a break in the filling process. 
However, there is an alternate format of these requests which does not cause a 
break. That is the format where the initial period character (.) in the request 
is replaced by the apostrophe or single quote character ('). The list of 
requests that cause a break appears in the table below this one. 

A \p Function 

When filling is in effect, the in-line \p function may be embedded or attached 
to a word to cause a break at the end of the word and have the resulting output 
line spread out io fill the current line length. 

End of file 

FUling stops when the end of the input file is reached. 


Breaks caused by blank lines or spaces at the beginning of a line enable you to 
take advantage of the filling and justification features provided by t r o f f or 
nroff without having to use any troff ornroff requests in your text. 

As mentioned in the table above in the item entitled “troff or nroff 
requests,” there are some requests that cause a break when they are encountered. 
The list of requests fiiat break lines is short and natural: 
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Table 2-2 Formatter Requests that Cause a Line Break 


Command 

Explanation 

.bp 

Begin a new page 

.br 

Break the current output fine 

.ce 

Center Hne(s) 

1 • f i 

Start fining text fines 

. nf 

Stop fining text fines 

1 • sp 

Space verticaUy 

i . in 

Indent tte left margin 

. ti 

Temporary indent the left margin for the next fine only 


No other requests break lines, regardless of whether you use a . or a' as the con¬ 
trol character. If you really do need a break, add a . br (break) request at the 
appropriate place, as described below. 


. br — Break Lines The . br (break) request breaks the current output line and stops filling that line. 

Any new output will start on a new line. 


Summary of the .hr Request 

Mnemonic: 

break 

Form cf Request: 

.br 

Initial Value: 

Not Applicable 

If No Argument: 

cause break 

Explanation: 

Stop fining the fine currently being colected and output the line without 
acyustment. Text fines beginning with space characters and empty text lines 
(blank fines) also cause a break. 


Continuation Lines and 
Interrupted Text 


The copying of an input line in nofill (non-fin) mode (see below) can be inter¬ 
rupted by terminating the partial line with a \ c. The next encountered input text 
line win be considered to be a continuation of the same Une of input text Simi¬ 
larly, a word within text may be interrupted by terminating the word (and 
line) with \ c; the next encountered text wOl be taken as a continuation of the 
interrapted word. If the intervening control lines cause a break, any partial fine 
win be forced out along with any partial word. 
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2.2. Justifying Text and 
Filling Lines 

. ad — Specify Adjusting To change the style of text justification, usse the . ad (adjust) request to specify 

Styles one of the four different methods for adjusting text: 

Table 2-3, Adjusting Styles for Filled Text 


Adjusting 

Indicator 

Adjusting 

Style 

Description 


.ad 1 

Left 

Produces flush-left, ragged-right output, 
is the same as filling with no adjustment. 

which 

.ad r 

Ri^t 

Produces flush-right, ragged-left output 


.ad c 

Center 

Centers each output line, giving both left and 



ri^t ragged margins. 


.ad b 
.ad n 

Both 

Normal 

Justifies both left and right margins. 


.ad 

Reset 

Resumes adjusting lines in the last 
requested. 

mode 


It makes no sense to try to adjust lines when they are not being filled, so if filling 
is off when a . ad request is seen, the adjusting is deferred until filling is turned 
on again. 


Summary of the .ad Request 

Mnemonic: 

adjust 

Form of Request: 

. ad c 

Initial Value: 

.ad b—that is, adjust both margins. 

If No Argument: 

Adjust in the last specified adjusting mode. 

Explanation: 

Adjust lines — if fill mode is off, adjustment is be deferred until fill mode is 
back on. If the type indicator c is present, the adjustment type is changed as 
shown in Table 2-3. 

Notes: 

E (see Table A-2) 


The current adjustment indicator c can be obtained from the . j number register. 

The following figure illustrates the different appearances of filled and justified 
text. 
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This paragraph is filled and adjusted on both margins. This is the easiest formatting style to achieve 
using nrof f or trof f because you don’t,have to place any requests in your text — you just type the 
blocks of text into the input file and the formatter does something reasonably sane with them. Although 
we specified nothing to get the paragraph filled and adjusted, we could have used an . ad b (adjust 
both) request, or a . ad n (adjust normal) request — they both mean the same thing, namely, fill lines 
and adjust both margins. 


This paragraph is an example of ‘flush left, ragged right’, which is what you get when you have fitting 
without adjusting — words are placed on the line to fill lines out as far as possible, but no interword 
spaces are inserted so the right-hand margin looks ragged. This paragraph was formatted using an . ad 
1 (adjust left) request, which has the same effect as using a . na (no adjust) request described later. 


Then this paragraph is an illustration of text formatted as ‘ flush right, ragged left’ — words are placed on 
the line to fill lines out as far as possible, then the lines are made to line up on the right-hand margin, no 
interword spaces are inserted, and so the left-hand margin looks ragged. This paragraph was formatted 

using an . ad r (adjust right) request. 


Finally, this paragraph is an instance of a formatting style called ‘centered’ adjusting, also known as 
‘ragged left, ragged right’ — words are placed on the line to fill lines out as far as possible, then the lines 
ate centered so that both margins look ragged. This paragraph was formatted using an . ad e (adjust 

center) request 


Figure 2-1 Filling and Adjusting Sty les 

• A((justing If you don’t specify otherwise, trof f or nroff justifies yourtext so that both 

left and right margins ate straight. Thrs can be changed if necessary — one way, 
as we showed above, is to use the . ad 1 request to get left adjusting only so 
that the left margin is straight and the right margin is ragged. Another way to 
achieve this same effect is to use the . na (no adjust) request. Output lines are 
still filled, providing that filling hasn’t also been turned off— see the . nf (no 
fill) and . f i (fil) requests below. If filling is still on, trof f or nroff pro¬ 
duces flush left, ragged right output. To turn adjusting back on (return to the pre- 
vious state), use the . ad request. 
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Summary of the .na Request 

Mnemonic: 

no adjust 

Form of Request: 

.na 

Initial Value: 

Adjusting is on by default 

If No Argument: 

adjusting is turned off 

Explanation: 

Turn off adjustment — the right margin will be ragged. The adjustment 
type for the . ad request is not changed. Output lines are still filled if fill 
mode is on. To turn acyusting back on (return to the previous state), use the 
. ad request. 

Notes: 

E (see Table A-2) 

. nf and . f i — Turn Filling 
Off and On 

The . nf (no fill) request turns off filling. Lines in the result are neither filled 
nor adjusted. The ouq)ut text appears exactly as it was typed in, complete with 
any extra spaces and blank lines you mi^t type — this is often called ‘as- 
is text’, or ‘verbatim’. No filling is mainly used for showing examples, espe¬ 
cially in computer books where you want to show examples of program source 
code. 


You should be aware that traditional typesetting people have trouble with tiie 
concept of no filling, because their typesetting systems are geared up to fift and 
adjust text aU the time. When you ask for stuff to be printed exactly the way you 
typed it, they have problems, especially when you want blank lines left in the 
unfilled text exactly where you put them. In the world of typography , things that 
don’t fit into the Procrustean mold of filled text are often called ‘displays’ and 
have to be handled specially . 


The . £ i (flU) request turns on filling. If adjusting has not been turned off by a 
. na request, output lines are also adjusted in the prevailing mode set by any pre¬ 
vious . ad request. 

Summary of the .fill Request 

Mnemonic: 

fiU 

Form of Request: 

. f i 

Initial Value: 

Riling is on by deftmlt 

If No Argument: 

filling is turned on 

Explanation: 

Fill subsequent ouqmt lines. The number register . u is 1 in fill mode and 0 
in nofiU mode. 

Notes: 

E,B (see Table A-2) 
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Summary of the , ^ t Request 

Mnemonic: 

no fill 

Form of Request: 

.nf 

Initial Value: 

Filling is on by default 

If No Argument: 

filling is turned off 

Explanation: 

Subsequent output lines are neither filled nor adjusted. Input text lines are 
copied directly to output lines without regard for the current line length. 

The number register , u is Tin fill mo^ and 0 in noflU mode. 

Notes: 

E,B (see Table A-2) 


2.3. Hyphenation 


. nh and , hy — Control 
Hyphenation 


When troff or nr of f fills lines, it takes each word in turn from the input text 
line, and puts the word on the output text line, until it finds a word that will not 
fit on the output line. At thus point, t r of f or nr of f tries to hyphenate the 
word. If possible, the first part of the hyphenated word is put on the output line 
followed by a -, and the remainder of the word is put on the next line. We 
should emphasize that, although the examples show text that is both filled and 
justified, it is during filling that troff or nroff hyphenates words, not adjust¬ 
ing. ^ 

( ; 

If you have words in your input text containing hyphens (such as jack-in-the-box, 
or co-woifcer), troff or nrof f wiU, if necessary, split these words over two 
lines, even if hyphenation is turned off. 


Normally, when you invoke troff or nrof f , hyphenation is turned On, but 
you can change this. The . nh (no hyphenation) request turns off automatic 
hyphenation. When hyphenation is turned off, the only words that are split over 
more than one line are those that already contain h 5 ^hens. Hyphenation can be 
turned on again with the . hy (hyphenate) request. 

You can give . hy an argument to restrict the amount of hyphenation that troff 
or nroff does. The argument is numeric. The request .hy 2 stops troff or 
nr o f f from hyphenating the last word on a page. . hy 4 instructs t ro f f or 
nroff not to split the last two characters from a word; so, for example, 
‘repeated’ will never be hyphenated ‘repeat-ed’. . hy 8 requests the same thing 
for the first two characters of a word; so, for example, ‘repeated’ will not be 
hyphenated‘re-peated’. 

The values of the arguments are additive: . hy 12 makes sure that words like 
‘repeated’ will never be hyphenated either as ‘repeat-ed’ or as ‘re-peated’. . hy 
14 calls up aU three restrictions on hyphenation. 

A . hy 1 request is the same as the simple . hy request — it turns on hyphena¬ 
tion everywhere. Finally, a .hy 0 request is the same as the .nh request — it 
turns olf automatic hyphenation altogether. 
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Only words that consist of a centtal alphabetic string surrounded by (usually 
null) non-alphabetic strings are considered candidates for automatic hyphenation. 
Words that were input containing hyphens (minus), em-dashes (\ ( em), or 
hyphenation characters — such as mother-in-law — always subject to split¬ 
ting after those characters, whether or not automatie hyphenation is on or off. 


Summary of the . n h Request 

Mnemonic: 

no hyphenation 

Form off Request: 

.nh 

Initial Value: 

Hyphenation is on by default 

If No Argument: 

hyphenation is turned off 

Explanation: 

Turn automatic hyphenation off. 

Notes: 

E (see Table A-2) 


Summary of the .hy Request 

Mnemonic: 

hyphenation 

Form of Request: 

.hy iV 

Initial Value: 

Hyphenation is on by default in mode 1. 

If No Argument: 

N=\. 

Explanation: 

Turn automatic hyphenation on for N >\, or off for iV=0. If n=1, all words 
are subject to hyphenation. If N=2, do not hyphenate last lines (ones that 
cause a trap). If N =4, do not hyphenate the last two characters of a word. If 

N =8, do not hyphenate tht first two characters of a word. These values are 
additive — that is, iV=14 invokes all three restrictions. Note: odd values of 

N (except 1) don’t make sense. 

Notes: 

E (see Table A-2) 


.hw—Specify Hyphenation Ifthereare words that you want troff ornroff to h 3 rphenate in some special 
Word List way, you can specify them with die . hw (jiyphenate words) request This 

request teUs troff or nrof f that you have special cases it should know about, 
for example: 



A 

.hw pre-empt ant-eater 


___ 

. j 


Now, if either of the words ‘preempt’ or ‘anteater’ need to be hyphenated, they 
wiU appear as specified in the . h w request, regardless of what t r o f f or 
nrof f’s usual hyphenation rules wo^d do. If you use the . hw request, be 
aware that there is a limit of about 128 characters in total, for the list of special 
words. 
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Summary of the . Request 

Mnemonic: 

hyphenate word 

Form cf Request: 

.hw wordl ... 

Initial Value: 

None 

If No Argument: 

Ignored 

Explanation: 

Specify hyphenation points in words with embedded minus signs. Versions 
of a word with terminal s are implied — that is, dig-it implies dig-its. This 
list is examined initially after each suffix stripping. The space available 
is small — about 128 characters. 


.he — Specify Hyphenation 
Character 


A hyphenation indicator character may be embedded in a word to specify desired 
hyphenation points, or may precede the word to suppress hyphenation. For 
example, hyphenation looks particularly disruptive if it occurs in titles. So, if 
you had a long title like: 

Input and Output Conventions and Character Translations, 

you could shorten it, or you could insert the hyphenation character just before the 
first character of each of the long words at the end of the title. The input might 
look like this: 


.H C "Input and Output Conventions and \%Character \%Translations" 


(If you are using a reasonable line length, you don’t need to worry about hyphe¬ 
nation occurring earliCT in the title in this example.) 

Here is an example of using the hyphenation character to specify acceptably 
hyphenation points within a word. The word “workstation” is often mis- 
hyphenated because of the collection of consonants at the end of “work” and the 
beginning of “station”. So, your input might look like this: 


r -—--- 

WO rk\% S tation 


V 

--- ) 
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Summary of the .fic Request 

Mnemonic: 

hyphenation character 

Form of Request: 

. he c 

Initial Value: 

\% 

If No Argument: 

\% 

Explanation: 

Set hyphenation indicator character to c or to the default \ %. The indicator 
does not appear in the output. 

Notes: 

E (see Table A-2) 


2.4, , ce — Center Lines of When we described “Filling and Adjusting,” we showed how the text produced 
Text by nrof f or trof f could be centered by using tiie . ad c request. Setting 

text adjustment for centering is a fairly unusual way of getting centered text, 
because the text is being filled at the same time. The more usual use for center¬ 
ing is to have unfilled lines that are centered — that is, each line that you type is 
centered within the output line. You get lines centered via the .ce (center) 
request, which centers lines of text. 


If you just use a . ce request without an argument, trof f or nrof f centers the 
nexrline of text; 



centers the following five lines of text. Filling is temporarily turned off when 
lines are centered, so each line in the input appears as a line in the output, cen¬ 
tered between the left and right margins. For centering purposes, the left margin 
includes botii the page offset (see later) and any indentation (also see later) that 
may be in effect. 

An argument of zero to the . ce request simply stops any centering that might be 
in progress. So, if you don’t want to counthow many lines you want centered, 
you can ask for some large number of lines to be centered, then follow the last of 
the lines with a . ce 0 request: 
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.ce 100 


lines of text to be centered 


.ce 0 


The ‘ 100’ in the example above could be any large number that you think is 
bigger than the number of lines to center. 

Note that the argument to the . ce request only aj^lies to following text lines in 
the input. Lines containing nrof f or trof f requests are not counted. 


Summary of the . CQ Request 

Mnemonic: 

center 

Form of Request: 

. ce N 

Initial Value: 

Centering is off by default. ' 

If No Argument: 

N=1 

E:iq)lanation: 

Center the next N input text lines within the current line (line-length minus 
indent). IfN=0, any residual count is cleared. A break occurs after each of 
the N input lines. If the input line is too long, it is left adjusted. 

Notes: 

E,B (see Table A-2) 


2.5. .uland.cu — 
Underline or 
Emphasize Text 


There are times when you want to lend emphasis to a word in a piece of text. 
The normal way to do this is to place the word or piece of text in italics if you 
have an italic font, or underline the word if you don’t have an italic font. The 
. ul (underline) request underlines alphanumeric characters in nrof f , and 
prints those characters in the italic font in t ro f f. As with the . ce request, a 
. ul request with no argument tmderlines a single line of text, so: 

( ------- 

.ul 

following line of text 


simply underlines the following line of text Unlike . ce, though, . ul does not 
turn filling off. A numeric argument to the . ul request specifies the number of 
text lines you want underlined, so: 


.ul 3 


underlines the next three lines of text. As with centering, an argument of zero 
. ul 0 cancels the underlining process. 
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Summary of the . u l Request 

Mnemonic: 

underline 

Form of Request: 

.ul N 

Initial Value: 

Underlining is off by default. 

If No Argument: 

iV=l 

Explanation: 

Underline in nrof f (italicize in trof f) the next N input text lines. Actu¬ 
ally, switch to underline font, saving the current font for later restoration; 
other font changes within the span of a . ul wifi, take effect, but the restora¬ 
tion will undo the la^ change. Output generated by a . 11 request is 
affected by the font change, but does not decrement N: If AZ > 1, there is the 
risk that a trap-interpolated macro may provide text lines within the span — 
environment switching can prevent this. 

Notes: 

E (see Table A-2) ^ 


Anotitier fomi of underlining is called up witii the . eu request, and asks for con¬ 
tinuous underlining. This is the same as the . ul request, except that a/Z charac¬ 
ters are imderlined. Again, if you are using t ro f f the characters are printed in 
the italic font instead of underlined. There is a way to get characters underlined 
in trof f, and this technique is explained later in this manual. 

As with . ee, only lines of text to be underlined are counted in the number given 
to the underline request nr of f or trof f requests interspersed with the text 
lines are not counted. 



Summary of the . cu Request 

Mnemonic: 

continuously imderhne 

Form of Request: 

.eu# 

Initial Value: 

Underlining is off by default. 

If No Argument: 

#=1 1 

Explanation: 

A variant of . ul that underlines every character in nrof f. Identical to 
.ulintroff. 

Notes: 

E (see Table A-2) 


2.6. . u f — Underline Font nr of f automatically underlines characters in the underline font, specifiable 

with a . uf (underline font) request. The underline font is normally Times Italic 
and is mounted on font position 2. In addition to the . ft (font) request and the 
\ f F, the imderline font may be selected by the . ul (underline) request and the 
. Gu (continuous underhne) request. Underlining is restricted to an output- 
device-dependent subset of reasonable characters. 
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Summary of the . uf Request 

Mnemonic: underline font 

Form cf Request: .ufF 

Initial Value: Italic 

^No Argument: Italic 

Explanation: Set underline font to F. In nro f f, F may ruot be on position 1 (initially 

Times Roman). 
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Page Layout 


Now we get into liie subject of altering tiie physical dimensions of the layout of 
text on a page. There are two major parts to page control, and they can be 
roughly divided into controlling fte horizontal aspects of lines, and controlling 
the vertical aspects of the page dimensions. 

Horizontal page control Deals with subjects such as the location of the left margin, the location of the 

right margin (the length of the Une), and indentation of lines. 

Vertical page control Deals with the physical length of the page, when pages get started, and whether 

there’s enough room on the current page for a block of text. Page numbering is 
also covered in this area. 

These topics are covered in this section. We deal first with horizontal page con¬ 
trol, then with the vertical aspects of page control. 

We should explain how t r o f f thinks of a page. The next page contains a 
diagram of a page of text, and here we explain what some of the terms mean: 

Page Offset is the distance from the physical edge of the paper to the place where all text 

begins. In normal-world terms, this distance is called the ‘left margin’. Nor¬ 
mally you only set dw page-offset at the very start of a formatting job and you 
never change it again. 

Line Length is the distance from tiie left margin (or page-offset) to the right edge of die text. 

The line-length is relative Xo the page-offset In some respects, ‘line-lengdi’ is a 
bit of a misnomer, because once you have set the page-offset at the start of the 
document (and assuming you never change it), the line-length really nails down 
the position of the right margin and has little to do with the length of die line. 

Indent is where the left edge of your text starts. Normally the indent is zero, so that the 
edge of the text is where die page-offset is, but you can change die indent so that 
the text starts somewhere else. Note that the line-lengdi is not affected by the 
indent — that is, indenting the text doesn’t change the position of the right mar¬ 
gin. 

Page Length is the distance ftom the extreme top of the page to the extreme bottom of the 
page, that is, the page length is the physical length of the paper. 

The following figure is a diagram of a page of text with the relevant parts pointed 
out. This diagram is a scale-model of an 8.5 x 11-inch sheet of paper, so while 
the numbers quoted in the text below are expressed in ‘real’ units, the actual 
dimensions are scaled. 
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Rgure 3-1 Layout of a Page 


left header center header right headar 

This paragraph has the page-offset set to give a left margin of approximately one inch (scaled). The 
line-length is set to 6.5 inches (scaled). This means there is a one-inch (scaled) left margin and a one- 
inch (scaled) right margin. The indent is set to zero so that the current left margin is at the same place 
as the page-offset. 

This paragraph has the page-offset and the line-length the same as the last paragraph, but 
we’ ve used a . in tt- 0.5 i request to indent the left margin by half an inch — the current left 
margin is now page-offset+indent. Note that the position Of the right margin remains the 
same as in the previous paragraph — only the left margin moved, so the effective length of the 
lines is shorter. 

This paragraph now has the left margin back to the original position because we inserted a . in 
- 0.5 i request before it. 


This paragraph could have the left margin moved, not by indenting, but by changing the page-offset via 
a . po +0.5 i request. Now all text would be moved to the left, and because (he line-length hasn’t 
changed, the right margin would move as well. The example can’t show this because page offset is 
measured from the margin, and because this example is in a box, changing the page offset within the 
box is meaningless. 

This is the regular old paragraph where the first line is indented and the rest of the text in the para¬ 
graph is flushed to the left margin. The first line was indented via a .ti + 0.2 5i request to give a 
temporary indent Of the first line. 


• This paragraph is an example of an ‘item’ or ‘bulleted’ or ‘hanging’ paragraph, where the left mar¬ 
gin is moved to the right, and (he ‘bullet’ or ‘tag’ is moved back to the old left margin. This effect 
was achieved via a . in + 0.2 5 i request to move the left margin rightward, and then the ‘bullet’ 
was preceded by a . tl -0.25i request to get a temporary indent to the old position of the left 
margin. 

Finally, note that tab stops are relative to the current left margin as we show here with a couple of 
blocks of text with different indents. Note that the positions of the tab stops are shown with exclama¬ 
tion point (!) characters: 

! 5 ! ! ! 

You can see by the line Of ! marks above where the tab stops are. 

Now we have another block of text here but with the indent moved over a half-inch. As you 
can see by the line of ! marks below, the tab stops have moved with the left marein- 
! ! ! ! ! ! 


left footer 


center footer 


right footer 
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3.1. Margins and As we said above, flie positions of the left-hand and right-hand margins are con- 

indentations troUed via the page-offset and the line-length. Afterthat, any movements of the 

left-hand margin are controlled via indent and temporary indent requests. These 
topics are discussed in the following subsections. 


. po — Set Page Offset The usable page width on the Graphic Systems phototypesetter is about 7.54 

inches, beginning about 1/27 inch from the left edge of the 8 inch wide, continu¬ 
ous roll paper. The physical limitations on nr of f output are output-device 
dependent 

The page-offset is the distance from the extreme left-hand edge of the paper to 
the left margin of your text When you uire ‘standard’ 8.5x11-inch paper, it is 
customary to have the left and right margins be one inch each, so that die physic 
cal length of the printed lines are 6.5 inches — or you’d say that the measure was 
39 picas if you’re a typographer and can’t handle inches. 

In general, you only set the page-offset once in the course of fonnatting a docu¬ 
ment. Setting the page-offset determines the position of the physical left margin 
for the text, and then you (almost) never change the page-offset again — all 
indentation is done via . in (indent) requests and . ti (temporary indent) 
requests. We talk about these requests later in this part of the manual. 

The position of the physical right margin for the text is determined by the line- 
lengto relative to the page-offset The . 11 (line length) request is discussed 
below. 


Summary of the .^o Request 

Mnemonic: 

page offset 

Form of Request: 

.po±N 

Initial Value: 

0 in nr o f f, 26/27 inch in t r of f. 

If No Argument: 

Previous value 

Explanation: 

Set the current 10 margin to ±N. In t r o f f the initial value is 26/27 inch, 
which provides about one inch of paper margin including the physical 
typesetter margin of 1/27 inch. In trof f the maximum (line- 
lengdi)+(page-offset) is about 7.54 inches. In nrof f the initial page-offset 
is zero. 

Notes: 

V (see Table A-2) 


The current page-offset is available in the . o register. 


. 11 — Set Line Length trof f gives you full control over the lengdi of the printed lines. By die way, 

typographers don’t use terms like ‘line-lengdi’, they use the word ‘measure’ to 
mean the lengdi of a line. They always measure vertical distances in ‘picas’. 

Nevertheless, to set the line-length in t ro f f, use die . 11 (line length) request, 
asin 
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{ --\ 

; .11 6i 

-—_ _ _- 

As with the . sp request, the actual length can be specified in several ways — 
inches are probably the most intuitive unless you live in one of the very few 
places in the world where they don’t use inches. 

The maximtun line-length provided by the typesetter is 7.5 inches, by the way. 

To use the full width, you have to reset the default physical left margin (‘page- 
offset’), which is normally slightly less than one inch from the left edge of the 
paper. This is done by the . po (page offset) request discussed above. 


— 


o 

O 



--/ 


sets the offset as far to the left as it will go. 

Note that the line-length indues indent space but wot page-offset space. The 
line-length minus the indent is the basis for centering with the . ce request. The 
effect of the . 11 request is delayed, if a partially-collected line exists, until after 
that line is output. In fil mode, the length of text on an output line is less than or 
equal to the line-length minus the indent. The current line-length is available in 
the . 1 number register. The length of fliree-part titles produced by a . 11 
request (see Chapter 7, Titles and Page Numbering) is independent of the line- 
length set by the .11 request — the length of a three-part title is set by the . It 
request. 


Summary of the .11 Request 

Mnemonic: 

line length 

Form (^Request: 

.iim 

Initial Value: 

6.5 inches 

If No Argument: 

Previous value 

Explanation: 

Set the line-length to N where N is the value of the line length, or an incre- 
mait or decrement for the line-length. In troff the maximum (line- 
length)+(page-offset) is about 7.54 inches. 

Notes: 

E, m (see Table A-2) 


.in — Set Indent 


Given that you’ve got your page-offset and line-length correctly set for a docu¬ 
ment to establish the position of the left and right margins, you now make all 
other movements of the left margin via the . in (indent) request discussed here, 
and via the . ti (temporary indent) request described below. 

The . in (indent) request indents the left margin by some specified amount fiom 
the page-offset. This means that all the following text will be indented by the 
specified amount until you do something to change the indent. To get only the 
first line of a paragraph indented, you don’t use the . in request, but you use the 
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. t i (temporary indent) request described below. 

As an example, a common text structure in books and magazines is the ‘quota¬ 
tion’ — a paragraph that is indented both on the right and the left of the line. A 
quotation is used for precisely that purpose, namely to set some text off from the 
rest of die copy. We can achieve such a paragraph by using the .in request to 

move the left margin in, and the . 11 request to move the right margin leftward: 
--- 

;.in +0.5i 

1.11 -0.5i 

I I was to learn later in life that we tend to meet any new 
i situation by reorganizing; and a wonderful method 
it can be for creating the illusion of progress 
I while producing confusion, inefficiency, and demoralization. 

1.11 +0.5i 
.in -0.5i 

_ J 

When you format the above construct you get a block that looks like this: 

I was to learn later in life that we tend to meet any new situation 
by reorganizing; and a wonderful method it can be for creating 
the illusion of progress while producing confusion, inefficiency, 
and demoralization.^ 

Notice the use of ‘+’ and ‘-’ to specify the amount of change. These change the 
previous setting by the specified amount rather than just overriding it. The dis¬ 
tinction is quite important: . 11 +2.01 makes lines two inches longer, whereas 
.11 2.01 makes them two inches long: 

—— -—— V 

.11 2.0i 

^ I was to learn later in life that we tend to meet any new 
situation by reorganizing; and a wonderful method 
i it can be for creating the illusion of progress 
while producing confusion, inefficiency, and^ demoralization, 
k.___^ 

I was to learn later in life that 
we tend to meet any new situa¬ 
tion by reorganizing; and a 
wonderful method it can be for 
creating the illusion of progress 
while producing confusion, 
jnefficiency, and demoraliza¬ 
tion. 

With .in, .11, and .po, the previous value is used ifno argument is specified. 
So, in the above example, the lines: 


^ Pi£tronius Arbiter^ AS), 
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Note that the line4ength includes indent space but not page-offset space. The 
line-length minus the indent is the basis for centering with the . c e request. The 
effect of the . i n request is delayed, if a partially collected line exists, until after 
that line is output. In fill mode the length of text on an output line is less than or 
equal to the line-length minus the indent. The current indent is available in the 
. i number register. 


Summary of the . i n Request 

Mnemonic: 

indent 


Form of Request : 

. i n ±A^ 


Initial Value: 

0 


If No Argument: 

Previous value 


Explanation: 

Set the indent to where N is the value of the indent, or an increment or 

decrement on the current value of the indent. The , in request causes a 
break. 


Notes: 

E,m (see Table A-2) 



. t i ^ Temporarily Indent The . t i (temporary indent) request indents the next text line by a specified 
One Line amount. 


A common application for . t i is where the first line of a paragraph must be 
indented just like the one you’re reading now. You get such a construct with a 
sequence like: 


/ --- ^^- 

-ti 3 

A coinmon application for . . . 

■N 


-— _ / 


and when the paragraph is formatted, the first line of the paragraph is 
indented by three specified units just like fiiis one. Three of what? The default 
unit for the . t i request, as for most horizontally-oriented requests — . 11 (line 
length), . in (indent), and . po (page offset) — is ems. An cm is roughly the 
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width of the letter ‘m’ in the current point size. Thus, an em is slw&ys propor¬ 
tional to the point size you are using. An em in size p is the number of p points 
in the width of an ‘m’. Here’s an em followed by an em dash in several point 
sizes to show why this is a proportioned unit of measure. You wouldn’t want a 
20-point dash if you are printing the rest of a document in 12-point text Here’s 
12-point text: 

m 

1—1 

Here’s 16-point text: 

m 
I—I 

And here’s 20-point text: 

Thus a temporary indent of . t i 3 in the current point size results in an indent 
of three m’s width or Immml. 

Although inches are usually clearer than ems to people who don’t set type for a 
living, ems have a place: they are a measure of size that is proportional to the 
current point size. If you want to make text that keeps its proportions regardless 
of point size, you should use ems for aU dimensions. Ems can be specified as 
scale factors direefly, as in . t i 2.5m. 

Lines can also be indented negaUvely if the indent is already positive: 


r 

A 

.ti -0.3i 


_ : - ^ - 

J 


moves the next line back three tenths of an inch. A common text structure found 
in documents is ‘itemized lists’ where the paragraphs are indented but are set off 
by ‘bullets’ or some such. Item lists are often called ‘hanging paragraphs’ 
because the first line with the item on it ‘hangs’ to the left. For example, you 
could type the following series of lines like this (we’ve deliberately shortened flie 
length of the line to illustrate the effects): 


msun 

XT microsystems 
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\ .114.01 

shorten lines for this example 

1 -in +0.21 

indent left margin by a fifth inch 

1 .ta +0.21 

set a tab for the hanging indent 

.ce 

center a line cf title 

Indent Control Requests 


.tl -0.21 

move left margin back temporarily 

\ (bu tab the \fL\&.po\fP 

request sets the 

page-offset to the desired amount thereby making | 

sure the left margin is 

correct. 

.ti -0.21 

move left mar gin back temporarily 

\ (bu tab the \fL \&. in\ fP 

request sets the 

indent from the left margin for all following text. 

ft 

H- 

1 

O 

ro 

H- 

move left margin back temporarily 

\ (buthe \fL\&.tl\fP 

request sets the indent for 

the following line of text only, thus providing for 

fancy paragraph effects. 

---; 


We had to play some tricks with tabs as well to get everything lined up, but that 
won’t affect the main point of the discussion. The tab markers in the lines above 
show where there’s a tab character, and the \ (bu sequence at the start of the 
lines gets you a bullet (•) like that — we’U show the special character sequences 
later in this manual. When you format the text as shown in the example above, 
you get this effect: 


hident Control Requests 

• the . po request sets the page-offset to the desired amount 
thereby making sure the left margin is correct. 

• the . in request sets the indent from the left margin for all 
following text. 

• the . t i request sets the indent for the following line of text 
only, thus providing for fancy paragraph effects. 

Remember that the line-length includes indent space but not page-offset space. 
The effect of a . t i request is delayed, if a partially collected line exists, until 
after that line is output. In fill mode the length of text on an output line is less 
than or equal to the line-length minus the indent. The current indent is available 
in the . i register. 


Summary of the .t± Request 


Mnemonic: 

Form wf Request: 
Initial Value: 

If No Argument: 
Explanation: 


Notes: 


temporary indent 
.tl±N 
0 

Ignored 

Indent the next output text line a distance ±N with respect to the current 
indent. The resulting total indent may not be negative. The current indent 
is not changed. The .ti request causes a hrcak. 

E, m (see Table A-2) 


micrasystems 
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3.2. Page Lengths, Page Neither nrof f nor troff provide any facilities for top and bottom margins on 

Breaks, and a page, nor for any kind of page numbering at all. The -ms macro package 

Conditional Page described in a previous section of this manual sets things up so that reasonable 

Breaks pagination with top and bottom margins and page numbers is done automatically. 

If you want top andbottom margins when using raw troff or nrof f, youhave 
^ to do some tricky stuff. The tricky stuff is done via traps and macros. The trap 

tells troff or nrof f whento do some processing for tiie margins (for exam¬ 
ple, you might set a trap to start the bottom margin 0.75 inches from the bottom 
of the page), and the macro defines w/tar to do when the trap is sprung. It is con¬ 
ventional to set traps for them at vertical positions 0 (top) and —N (N from the 
bottom). 

A pseudo-page transition onto the^rjf page occurs either when the first break 
occurs or when the first non-diverted text processing occurs. Arrangements for a 
trap to occur at the top of the first page must be completed before this transition. 

In the following tables, references to the current diversion mtm that the mechan¬ 
ism being described works during both ordinary and diverted ou^ut (the former 
considered as the top diversion level). Refer to Chapter 10 for more information 
on diversions. 


. pi — Set Page Length 

Justasthe .po, .11, ,in,and ,ti requests changed the horizontal aspects of 
the page, the . pi (page length) request determines the physical length of the 
page. In general you won’t need to use the .pi request because the standard set¬ 
ting is ri^t for all but the most esoteric purposes. 


Summary of the .^1 Request 

Mnemonic: 

page length 

Form of Request: 

.pl±N 

Initial Value: 

11 inches 

If No Argument: 

11 inches 

Explanation: 

Set page length to ±N. The internal limitation is about 75 inches in t r of f 
and about 136 inches in nrof f. The current page length is available in the 
. p number register. 

Notes: 

V (see Table A-2) 


. bp — Start a New Page This request causes a break and skips to a new page. 
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Summary of the Request 

Mnemonic: 

begin page 

Form cf Request: 

. bp ihN 

Initial Value: 

N=1 

If No Argument: 

Increment current page number by 1. 

Explanation: 

Eject the current page and start a new page. If±N is given, the new page 
number will be ihN. Also see the . ns (no space) request. The . bp request 
causes a break. 

Notes: 

V (see Table A-2) 


. pn — Set Page Number 


Summary of the . p n Request 

Mnemonic: 

page niunber 

Form ^Request: 

.pn±N 

Initial Value: 

N=1 

If No Argument: 

Ignored 

Explanation: 

The next page (when it occurs) will have the page number m A . pn 

request must occur before the initial pseudo-page transition to affect the 
page number of the first page. The current page number is in the % register. 


. ne Specify Space Needed In some applications you need to make sure that a few lines of text aU appear 

together on the same page. There are several ways to achieve this ranging from 
simple to complicated. One of the simplest ways is to use the . n e (need) verti¬ 
cal space request: 


• ne 3 specify we need at least three lines 

some 

lines 

of 

text 
to 
be 
kept 
on the 
same page 


The arrangemeiit of the . n e request specifies that if there are many lines of text 
in (say) a paragraph, at least three of the lines will appear together on the same 
page, otherwise a new page will be started. The object of this exercise is to avoid 
what typographers call ‘orphans’ —that is, the first line of a paragraph appearing 



Revision A, of 9 May 1988 








Chapter 3— Page Layout 43 


all alone and lonely on the bottom of a page, while the rest of the paragraph 
appears on the next page. This is generally considered to be somewhat ugly and 
should be avoided if possible. By itself, trof f is too stupid to recognize the 
existence of orphans (indeed of any text constmcts at aU), but the facilities are 
there to avoid these situations. In general, macro packages such as the -ms 
macro package discussed elsewhere have ‘begin paragraph’ macros such as . pp 
which take care of controlling orphans. 

Summary of the .ne Request 

Mnemonic: 

need 

Form of Request: 

. ne N 

Initial Value: 

Not applicable 

If No Argument : 

IV 

Explanation: 

Need N vertical space. If the distance, D, to the next trap position is less 
than N, a forward vertical space of size D occurs, which will spring the trap. 

If there are no remaining traps on the page, D is die distance to the bottom 
of the page. If D < V, another line could stiU be output and spring the trap. 

In a diversion, D is the distance to the diversion trap, if any, or is very large. 

Notes: 

V (see Table A-2) 

3.3. Multi-Column Page 
Layout by Marking 
and Returning 

It is possible to achieve multi-colutrm output in trof f or nrof f via the .mk 
(mark) and . rt (return) requests. Other useful special effects can also be 
obtained using these requests, but one of the common uses is to do multi-column 
output. Basically, the . mk request marks the current vertical position on the 
page (you can place the result of the mark in a register). You do a coliunn’s 
worth of ouq)ut, then when you get to the end of the page, instead of starting the 
next page, you return (via the . rt request) to the maiked position, set up a new 
indent and line-length, and crank out anotiier column. 

. mk — Mark Current 

Vertical Position 


Summary of the .xtfk Request 

Mnemonic: 

made 

Form of Request: 

,mk R 

Initial Value: 

Not applicable 

If No Argument: 

R is an internal register 

Explanation: 

Mark tiie current vertical place in an internal register (both associated with 
the current diversion level), or in register i?, if given. See the . rt request. 
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. rt — Return to Marked 
Vertical Position 


Summary of the . rt Request 

Mnemonic: 

return 

Form cf Request: 

. r t ±V 

Initial Value: 

Not applicable 

If No Argument: 

return to place marked by a previous . mk request. 

Explanation: 

Return Mpmrrdonfy to a marked vertical place in the current diversion. If 
+N (with respect to the current place) is given, the place is from the top 
of the page or diversion or, if N is absent, to a place marked by a previous 
. ink. Note that the . sp request (refer to the chapter Line Spacing and 

Character Sizes) rady be used in all cases instead of . rt by spacing to the 
absolute place stored in a explicit register, for example, using the sequence 1 

.mk R . . . . sp ~ \nl?u. 
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Line Spacing and Character Sizes 


4.1. .sp — Space 
Vertically 


I \ 


You get extra vertieal space with the . sp (space) request. A simple 


r 

-^- 

.sp 


K _ 

J 


request with no argument gives you one extra blank line (One . vs, whatever that 
has been set to). Typically, that’s more or less than you want, so , sp can be fol¬ 
lowed by information about how much space you want — 



means ‘ two vertieal spaces ’ — two of whatever . vs is set to (this can also be 
made explicit with . sp 2v)*, trof f also understands decimal fractions in most 
places, so 


.sp 1.5i 

<____ _—- 


is aspaee of 1.5 inches. These same scale factors can be used after the .vs 
request to define line spacing, and in fact after most requests that detd with physi¬ 
cal dimensions. 

It should be noted that all size numbers are converted internally to ‘machine 
units’, which are 1/432 inch (1/6 point). For most purposes, this is-^enou^ reso¬ 
lution that you don’t have to worry about tiie accuracy of the representation. The 
situation is not quite so good vertically, where resolution is 1/144 inch (1/2 
point). 


wsun 

XT mlcros^tems 
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Summary of the . s p Request 

Mnemonic: 

space 

Form of Request: 

. sp N 

Initial Value: 

Not applicable 

If No Argument: 

iV=lV 

Explanation: 

Space vertically in di/Zier direction. If N is negative, the motion is 
(iqjward) and is limited to the distance to the top of the page. Forward 
(downward) motion is tmncated to the distance to the nearest trap. If the 
no-space mode is on, no spacing occurs (see . ns, and , rs below). 

Notes: 

B, V (see Table A-2) 


4.2. . ps — Change the 
Size of the Type 


6 point: Pack my box wi& five dozen liquor jugs. 

7 point: Pack my box with five dozdn liquor jugs. 

8 point: Pack my box with five dozenliquor jugs. 

9 point: Pack my box with five dozen liquor jugs. 

10 point: Pack my box with five dozen liquor jugs. 

11 point: Pack my box with five dozen liquor jugs. 

12 point: Pack my box with five dozen liquor jugs. 

14 point: Pack my box with five dozen liquor jugs. 

16 point: Pack my box with five dozen liquor jugs. 

18 point: Pack my box with five dozen liquor jugs. 

20 point: Pack my box with five dozen liquor jugs. 

22 point: Pack my box with five dozen liquor jugs. 

24 point: Pack my box with five dozen liquor jugs. 

28 point: Pack my box with five dozen liquor 

36 point: Pack my box with five doz 

If the number after a . ps request is not one of these legal sizes, it is rounded up 
to the next valid value, with a maximum of 36. If no number follows .ps, 
troff reverts to the previous size, whatever it was. troff begins with point 
size 10, which is usually fine. This document is in ll-point 


In troff, you can change the physical size of the characters that are printed on 
the page. The . ps (point size) request sets the point size. One point is 1/72 
inch, so 6-point characters are at most 1/12-inch high, and 36-point characters are 
1^-inch. troff and the machine it was originally designed for imderstand 15 
point sizes, listed below. 
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The point size can also be changed in the middle of a line or even a word with an 
in-line size change sequence, hi general, text which is in ALL CAPITALS in the 
middle of a sentence tends to loom large over the rest of the text and so it is cus¬ 
tomary to drop the point size of the capitals so that it looks like ALL capitals 
instead. You use die \ s (for size) sequence to state what the point size should 
be. You can state the size explicitly as in this line here: 

I' >, 

The \s8POWER\sO of a \s8SUN\sO 

V_ J 


to produce the output line like: 

The POWER of a SUN 

As above, \ s should be followed by a legal point size, except ttiat \ s 0 makes 
the size revert to its iM'evious value (before you just changed it). 

Note that because there are a fixed number of point sizes that the system knows 
about, the sequence \ s 96 gets you a nine-point 6 instead of 96;point type like you 
wanted, whereas tiie sequence \sl80 gets you an 18-point (Jinstead of 180- 
point type. 

Stating the point size in absolute terms as above is not always a good idea — 
what you reaUy want is for the changed size to be relative to the surrounding text, 
so that if your document is ih 11-point type like this one, you’d reaUy like Ihe 
bigger (or smaller stuff) to be a couple of points different without your having to 
know explicitly what the actual size is. So in this case, you can use a relative 
size-change sequence of the form \ s+ n to raise the point size, and \ s- n to 
lower the point size. The number «is restricted to a single digit. So we can 
rework our previous example from above like this: 


The \s-2POWER\s+2 of a \s-2SUN\s+2 

A 

J 

to produce the output line like: 

/ - 


The POWER of a sun 


V _ _ 

J 


Relative size changes have the advantage that the size difference is independent 
of the starting size of the document. Of course this stuff only works really well 
(in typography terms) when the changes in size aren’t too violently out of whack 
with the point size — a change of two points in 36-point type doesn’t have quite 
the same impact as it does for 12-point type — there is a question of the weight 
of the type, but by the time you get to that stuff you’ll be much more knowledge¬ 
able about typography. 

The current size is available in the . s number register, nrof f ignores type size 
control. 
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Summary of the .ps Request 

Mnemonic: 

point size 

Form of Request: 

.ps -MN 

Initial Value: 

10 points 

If No Argument: 

Previous value 

Explanation: 

Set point^size to ±N. Alternatively embed \ sN or \ sii/V. Any positive size 
value may be requested; if invalid, the next larger valid size will result, with 
a maximum of 36. The sequence 

.ps tJV 
. ps N 

wolks the same as 

.ps +N 
.ps ~N 

because the previous requested value is also remembered. Ignored in 
nroff. 

Notes: 

E (see Table A-2) 


4.3. . vs — Change The other parameter that determines what the type looks like is the spacing 

Vertical Distance between lines, which is set independently of the point size. Vertical spacing is 

Between Lines measured from the bottom of one line to the bottom of the next. The bottom of 

the text on a line is often called the baseline. The vertical spacing is often called 
leading (pronounced Ted-ing’) and comes from the days when text was produced 
with lead slugs instead of electronic widgets like laser printers. 

You control vertical spacing with the . vs (vertical spacing) request. For run¬ 
ning text, it is usually best to set the vertical spacing about 20% bigger than the 
character size. For example, so far in this document, we have used 11-point type 
with a vertical line-spacing of 13 points between baselines. Typographers call 
this ‘ 11 on 13 ’, so when you hear some one say that a hook is set in ‘ 11 on 13 ’, 
you know that it’s 11 -point type with 13-point vertical spacing. 


So, somewhere at the start of this document, the macro package that formats this 
document for us had requests like: 
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the running text would look like this. After a few lines, you wiU agree it looks a 
little cramped. The right vertical spacing is partly a matter of taste, depending on 
how much text you want to squeeze into a given space, and partly a matter of 
traditional printing style. By default, trof f uses 10 on 12. 

Point size and vertical spacing make a substantial difference in the amount 
of text per square inch. This is 12 on 14. 

Point sixo and vertical spacing make a substantial di^erence in die amount oflext per square inch. POr example, 10 on 12uses about twice as much 
space as 7 on 8< This is 6 on 7 ; which is even smaller. It packs a lot more words per line, but you can go bli^ trying to read it. 

When used without arguments, bodi .psand .vs revert to the previous size and 
vertical spacing respectively . 

The vertical spacing between the base-lines of successive output lines can be 

set using the . vs request with a resolution of 1/144 inch = 1/2 point in trof f, 
and to the output device resolution in nr of f. V must be large enough to accom¬ 
modate the character sizes on the affected output lines. For the common type 
sizes (9-12 points), usual typesetting practice is to set Vto 2 points greater than 
the point size; trof f default is 10-point type on a 12-point spacing. This docu¬ 
ment is set in 11-point type with a 13-point vertical spacing. The current T is 
available in the . v number re^ster. 


Summary of the Request 

Mnemonic: 

vertical spacing 

Form of Request: 

. vs N 

Initial Value: 

1/6 inch in nrof f, 12 points in trof f. 

If No Argument: 

Previous value 

Explanation- 

Set vertical base-line spacing size V. Transient extra vertical space avail- 
^e with \x'N' (see secticni on \x Function). 

Notes: 

E, p (see Table A-2) 


4.4. .Is— Change Line Multiple-F line separation (for instance, double spacing) can be requested with 

Spacing the .is (linespacing)request. 
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Summary of the . I s Request 

Mnemonic: 

line spacing 

Form of Request: 

.IsN 

Initial Value: 

N=1 

If No Argument: 

Previous value 

Explanation: 

Set/me spacing to ±V. N—l Vs ('Wanfc /mejf;) are appended to each output 
text line. Appended blank lines are omitted, if the text or previous appended 
blank line reached a trap position. 

Notes: 

E (see Table A-2) 

4.5. \x Function — Get 
Extra Line-Space 

If a word contains a vertically tall construct requiring the output line containing it 
to have extra vertical space before and/or after it, the extra-line-space function 
\x W 'can be embedded in or attached to that word, hi this and other functions 
having a pair of delimiters around their parameter (here '), the delimiter choice 
is arbitrary, except that it can’t look like the continuation of a number expression 
for N. If N is negative, the output line containing the word will be preceded by N 
extra vertical space; if A/is positive, the output line containing the word will be 
followed by A/ extra vertical space. If successive requests for extra space apply 
to the same line, the maximum values are used. The most recently used post-line 
extra line-space is available in the . a register. 

4.6. . s V — Save Block of 
Vertical Space 

A block of vertical space is ordinarily requested using the . sp (space) request, 
which honors the no-space mode and which does not space past a trap. A con¬ 
tiguous block of vertical space may be reserved using the . s v request (see 
below). 

Summary of the . sv Request 

Mnemonic: 

save space 

Form cf Request: 

.svN 1 

Initial Value: 

Not applicable 

If No Argument: 

N=1V 

Explanation: 

Save a contiguous vertical block of size //. If the distance to the next trap is 
greater than N, N vertical space is output. No-^space mode has no effect. If 
this distance is less than N, no vertical space is immediately output, but N is 
remembered for later output (see the . os request). Subsequent . sv 
requests will overwrite any stiU-remembered N. 

Notes: 

V (see Table A-2) 


microsystems 
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u 


4.7. . o s— Output Saved 
Vertical Space 


Summary of the . o s Request 

Mnemonic: 

output saved space 

Form of Request : 

.OS 

Initial Value: 

Not applicable 

If No Argument: 

Output saved vertical space 

Explanation: 

Output saved vertical space. No-space mode has no effect. Used to finally 
output a block of vertical space requested by an earlier , sv request. 


4.8. . ns — Set No Space 
Mode 


Summary of the .ns Request 

Mnemonic: 

no-space mode 

Form of Request: 

.ns 

Initial Value: 

Not applicable 

If No Argument: 

Turn on no-space mode 

Explanation: 

Turn on no-space mode — When on, the no-space mode inhibits . sp 
requests and . bp requests wirAoMt a next page number. The no-space mode 
is turned off when a line of ouqjut occurs, or with . r s. 

Notes: 

D (see Table A-2) 


4.9. . rs — Restore Space 
Mode 



Summary of the .ns Request 

Mnemonic: 

restore space mode 

Form of Request: 

.rs 

Initial Value: 

Not applicable 

If No Argument: 

Turn off no-space mode 

Explanation: 

Restore spacing—turn off no-space mode. 

Notes: 

D (see Table A-2) 
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4.10. . s s —Set Size of 
Space Character 



Summary of the .ss Request 

Mnemonic: 

space-character size 

Form of Request: 

.ssN 

Initial Value: 

12/36 em 

If No Argument: 

Ignored 

Explanation: 

Set space-character size to N/36 ems. This size is the minitTnim word spac¬ 
ing in adjusted text. Ignored in nrof £. 

Notes: 

E (seeTable A-2) 


4.11. . cs — Set Constant- 
Width Characters 


Summary of the . cs Request 

Mnemonic: 

constant spacing 

Form cf Request: 

.csFNM 

Initial Value: 

Off 

If No Argument: 

Ignored 

Explanation: 

Constant character space (width) mode is set on for font F (if mounted); the 
width of every character is taken as W36 ems. If M is absent, the em is that 
ofthe character's point size; ifM is given, the em is M-points. All affected 
characters are centered in this space, including those with an actual width 
larger than this space. Special Font characters occurring while the current 
font is F are also so treated. UN is absent, the mode is turned off The 
mode must be stifl or again in effect when the characters are physically 
printed. Ignored in nrof f. 

Notes: 

P (see Table A-2) 
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Fonts and Special Characters 


t r of f and the typesetter allow four different fonts at any one time. Normally 
three fonts (Times Roman, italic and bold) and one collection of special charac¬ 
ters are permanently mounted. 

- 

abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHUKLMNOPQRSTUVWXYZ 
abcd^ghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHUKLMNOPQRSTUVWXYZ 

s_ 

The Greek, mathematical symbols, and miscellany of the special font are listed in 
Appendix B, Font and Character Examples. 


troff prints in Roman unless told otherwise. To switch into bold, use the .ft 
(font) request: 


r 

.ft B 

c _ 

J 

and for italics. 

r 

A 

.ft I 


V - 



To return to Roman, use .ft R; to return to the previous font, whatever it was, 
use either .ft For just .ft. 



57 
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5.1. . ft — Set Font 



Summary of the .ft Request 

Mnemonic: 

font 

Form (^Request: 

. ft F 

Initial Value: 

Roman 

If No Argument: 

Previous Font 

Explanation: 

Change font to F. Alternatively, embed \ f F. The font name P is reserved 
to mean the previous font. 

Notes: 

E (see Table A-2) 


The ‘underline’ request 

--- 

.ul 


makes the next input line print in italics. . ml can be foUowed by a count to indi¬ 
cate that more than one line is to be italicized. Refer to Chapter 2 for a more 
detailed description of the . ml request. 

Fonts can also be changed within a line or word with the in-line request \ f: 

bol^oce text 
is produced by the input 


\fBbold\fIface\£R text 


If you want to do this so the previous font, whatever it was, is left undisturbed, 
insert extra in-line \ £P commands, like this; 


\ f BboldX f P \ f I f ace\ f P \ f R text \ f P 


Because only the immediately previous font is remembered, you have to restore 
the previous font after each change or you lose it. The same is true of . ps and 
. vs when used without an argument. 

There are other fonts available besides the standard set, although you can still use 
only four at any given time. The . £p (font position) request tells troff what 
fonts are physically moxmted on the typesetter: 


.fp 3 H 


says that the Helvetica font is mounted on position 3. Appropriate . fp requests 
should appear at the beginning of your document if you do not use the standard 
fonts. 
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5.2. .fp— Set Font 
Position 

It is possible to make a document relatively independent of the actual fonts used 
to print it by using font numbers instead of names; for example, \ f 3 and . ft 3 
mean ‘whatever font is mounted at position 3’, and thus work for any setting. 
Normal settings are Roman font (R) on font position 1, italic (I) on position 2, 
bold (B) on position 3, and special (S) on position 4 — tiie mnemonic ‘RIBS’ 
might help you remember. 


Summary of the .1^ Request 

Mnemonic: 

font position 

Form of Request: 

.fpiVF 

Initial Value: 

R,I,B,S 

If No Argument: 

Ignored 

Ejq>lanation: 

Fbnt position — this is a statement that a font named F is mounted on posi¬ 
tion N (1-4). It is a fatal error if F is not known. The phototypesetter has 
four fonts physically mounted. Each font consists of a film strip that can be 
mounted on a numbered quadrant of a wheel. The default mounting 
sequence assumed by trof f is R, I, B, and S on positions 1,2, 3 and 4. 

Any . fp request specifying a font on some position must precede . f z 
requests relating to that position. 


5.3. . f z — Force Font Size 


Summary of the . fz Request 

Mnemonic: 

font size 

Form of Request: 

.tzSFN 

Initial Value: 

None 

If No Argument: 

None 

Explanation: 

Forces font F or S for special characters to be in size N. A . f z 3 -2 
causes implicit \s^2 every time font 3 is entered, and a matehing \s+2 when 
left. Same for special font characters that are used during F. Use S to han¬ 
dle special characters during F. .fz 3 -3or.fz S 3 -0 causes 
automatic reduction of font 3 by 3 pointe while special characters are not 
affected. Any . f p request specifying a font on some position must precede 
. f z requests relating to that position. 


There is also a way to get ‘synthetic’ bold fonts by overstriking letters with a 
slight offset. Look at tile .bd request. 
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5.4. .bd — Artificial 
Boldface 

- 

Summary of the .hd Request 

Mnemonic: 

bold 

Form ef Request: 

.hdFN 

Initial Value: 

Off 

If No Argument: 

No Emboldening 

Explanation: 

Artificially embolden characters in font F by printing each one twice, 
separated by N-1 basic units. A reasonable value for N is 3 when the char¬ 
acter size is in the vicinity of 10 points. If AT is missing the embolden mode 
is turned off. The mode must be still or again in effect when the characters 
are physically printed. Ignored in nrof f. 

Form ef Request: 

.bd SFN 

Explanation: 

Embolden characters in the special font whenever the current font is F. The 
mode must be still or again in effect when the characters are physically 
printed. 

Notes: 

P (seeTable A-2) 


Special characters have four-character names beginning with \ (, and they may 
be inserted anywhere. For example, 


Va + V 2 = % 


is produced by 


\(14 + \ (12 = \{34 



---> 


In particular, Greek letters are all of the form \ ( *x, where x represents an upper- 
or lower-case ^man letter reminiscent of the Greek. Thus to get 

^ 

Z((XxP) -» « 


in raw trof f we have to type 


\ \ (-> \ (if 


That line is unscrambled as follows: 
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Escape 

Sequence 

Character 

Printed 

Description 

\(*S 

Z 

Upper-case Sigma or Sum 

( 

( 


: \ (*a 

a 

lower-case alpha 

\ (mm 

X 

multiplication sign or signum 

\ (*b 

V' 

p 

) 

-> 

lower-case beta 

) 

\(-> 

tends toward 

\ (if 

cx> 

infinity 


A complete list of these special names occurs in Appendix 'Q, Font and Charac¬ 
ter Examples. 

hi eqn, explained in the chapter “Formatting Mathematics with Qqa" va. Format¬ 
ting Doeuments, you can acWeve the same effect with the input 
- - 

SIGMA (alpha times beta ) “> inf 

V__/ 

which is less concise (31 keystrokes instead of 27!), but clearer to the uninitiated. 


Notice that each four-character name is a single character as far as t r o f f is con¬ 
cerned. For example, the translate request 



that is, to translate - (minus sign) into — (em-dash). 

Some characters are automatically translated into others: grave ' and acute 
accents (apostrophes) become open and close single quotes ‘ ’; the combination 
of “...” is generally preferable to the double quotes Similarly a typed 
minus sign becomes a hyphen -. To print an explicit - sign, use \ To get a 
backslash printed, use \ e. 


The trof f character set consists of die Graphics Systems Commercial 11 char¬ 
acter set plus a Special Mathematical Font character set — each having 102 char¬ 
acters. These character sets are shown in Appendix B, Font and Character 
Examples, All ASCII characters are included, with some on the Special Font. 
With three exceptions, the ASCII characters are input as themselves, and non- 
ASCII characters are input in the form \ (xx where xx is a two-character name 
also explained in Appendix B. The three ASCII exceptions are mapped as fol¬ 
lows: 
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Table 5-1 Exceptions to the Standard MCII Character Mapping 


ASCII Input 
Character Name 

Printed by f 

Character Name 

acute accent 
grave accent 
- minus 

close quote 
‘ open quote 

hyphen 



5.6. Fonts 


5.7. . ig — Control 
Ligatures 


The characters ', ', and — may be input by \ , \', and \— respectively or by 
their names found in Appendix B. The ASCII characters @, #, ", ',', <, >, \, {, 
}, , and _ exist only or the Special Font and are printed asa one-em space if 

that font is not mounted. 

nr of f xmderstands the entire trof f character set, but can in general print only 
ASCII characters, additional characters as may be available on the output device, 
such characters as may be constructed by overstriking or other combination, and 
those that can reasonably be mapped into other printable characters. The exact 
behavior is determined by a driving table prepared for each device. The charac¬ 
ters , and _ print as themselves. 


The default mounted fonts are Times Roman (R), Times Italic (I), Times Bold 
(B), and the Special Mathematical Font (S) on physical typesetter positions 1,2, 
3, and 4 respectively. These fonts and others are used in this document. The 
current font, initially Roman, may be changed (among the mounted fonts) by use 
of the . f t request, or by embedding at any desired point either \fx, \f (xc, or 
\ m where X and xc are the name of a mounted font and N is a numerical font 
position. It is not necessary to change to the Special font; characters on that font 
are automatically handled. A request for a named but not-mounted font is 
ignored, t r of f can be informed that any particular font is mounted by use of 
the .fp request. The list of known fonts is installation-dependent. In the subse¬ 
quent discussion of font-related requests, F represents either a one- or two- 
character font name or the numerical font position, 1 through 4. The current font 
is available (as numerical position) in the read-only number register . f. 

nrof f understands font control and normally underlines italic characters. 


A ligature is a special way of joining two characters together as one. Way back 
in the days before Gutenterg, scribes would have a variety of special forms to 
choose from to make lines come out all the same length on a manuscript. Some 
of these forms are still with us today. 

Five ligatures are available in the current t ro f f character set — fi, fl, ff, ffi, and 
flfl. They may be input (even in nrof f) by \ (fi, \ (f i, \ (f f, \ (Fi, and 
\ (Fl respectively. 


The ligature mode is normally on in trof f, and automatically invokes ligatures 
during input. ' ) 
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/■ 

W 

If you want other ligatures like the ae, oe, /E, andCE ligatures, you have to make 
them up yourself— trof f doesn’t know about them. See Chapter 12 the sec¬ 
tion on “Arbitrary Horizontal Motion” (the \h fimetion) for some examples on 
constructing these ligatures. 


Summary of the . Iq Request 

Mnemonic: 

ligature 

Form of Request: 

.IgN 

Initial Value: 

Off in nroff, onin trof f. 

If No Argument: 

on 

Explanation: 

Turn Ligature mode on if iV is absent or non-zero. Turn ligature mode off if 

N=0. If N-2, only the two-character ligatures are automatically invoked. 

Ligature mode is inhibited for request, macro, string, register, or file names, 
and in copy mode. Nb effect in nr of f. 
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Tabs, Leaders, and Fields 


There are several ways to get stuff lined up in columns, and to achieve other 
effects such as horizontal motion and repeated strings of characters. The three 
related topics we discuss in this section are rate , leaders , waA fields . 

tabs behave just like the tab stops on a typewriter. 

leaders are for generating repeated strings of characters. 

fields are a general mechanism for helping to line stuff up into 
columns. 

This part of the document concentrates on the ‘easy ’ parts, so to speak. Later 
sections of this document contain discussions on the facilities for drawing lines 
and for producing arbitrary motions on the page. 

6.1. . t a — Set Tabs Tabs (the ASai horizontal tab character) can be used to produce output in 

columns, or to set the horizontal position of output. Typically tabs are used only 
in unfilled text. Tab stops are set by default every half inch from the current 
indent (in trof f) and every 0.8 inch from the current indent (in nrof f), but 
can be changed by the .ta (tab) request In the example below, we set tab stops 
every one-and-a-half inches and set some text in columns based on those tab 
stops. We place a line of exclamation marks ( !) above and below the text to 

show where the tabs stops are in the ouq)ut page: 

—--- 

I .ta 1.5i 3.01 4.5i 6.01 set tabs 

\ tab \ tab \ tab \ tab I show where tabs are with ! character 

word-one toi) word-two la/>word^three toi>word^four to^word^five 
\tab\tab\tab\tab\ 

V_____ y 

When we format the above example, we get this output: 

! ! ! ! 

word-two word-three word-four word-five 

! ! ! ! 


! 

word-one 

! 
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Setting Relative Tab Stops The tab stops set in the example above are in terms of absolute position on the 

line. You could also set tabs relative to previous tabs stops by preceding the tab 
stop number with a + sign, and get exactly the same result: 


— 

.ta 1.5i +1 

5i +1.51 

+1.51 

> 

settabs 

! tab 

tab ! 

tab ! tab 

} 

show where tabs are with ! character 

word-one tab 

word-two 

tab word-three 

tab word-four tab word-five 

! tab 

tab ! 

tab ! tab 

1 

-—_ _ _ / 


Right-A^usted Tab Stops In the standard case as shown in the above examples, the tab stops are left- 

adjusted (as on a typewriter). You can also make the tab stops right-adjusting for 
doing things like lining up colunms of numbers. When you right-adjust a tab 
stop, the action of placing a tab before the field places the material behind the tab 
stop on the output line. Here’s an example of some input with both alphabetic 
and numeric items: 



Notice the . ta request — it has the letter R on the end to indicate that this is a 
right-adjusted tab. When we format that table, we get this result: 


July 

5 

August 

9 

September 

15 

October 

60 

November 

85 

December 

126 


Notice how the numbers in the second column line up. 

Centered Tab Stops Finally you can make centered tab stop, so that things get centered between the 

tabs. We can use the centering tabs to ixit a title on our table from above: 
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/ - 


.nf 


.ta 2.OiC 


Month tab Shipments 


•ta 2.0iR 


July tab 5 


August tab 9 


September tab 15 


October tab 60 


November tab 85 


December tofe 126 


.fi 


<_ 



en we format this table now 

, we get this 

Month 

Shipments 

July 

5 

August 

9 

September 

15 

October 

60 

November 

85 

December 

126 


Notice that the column headings are centered over the data in the table. 

If you have a complex table, instead of using trof f or nrof f directly, use the 
tbl program described in the chapter “Formatting Tables with tbl” in Format¬ 
ting Documents. A good example of where tbl does more work for you is when 
numerically-aligned items have decimal points in them — it is really hard to do 
this using the raw trof f ornroff capabilities. 


A tab inserts blank spaces between the item that came before and after it. You 
can change this by filling up tabbed-over space with some other character. Set 
the Tab replacement character’ with the . t c (tab character) request: 


/ 

A 

.ta 2.5i 4.5i 


; .tc _ 


1 Name tab AgQ tab 


V_:- 

_ _ > 


This produces 

Name_Age _ 

There is a more general mechanism for drawing lines, described in the sections 
“Drawing Vertical Lines” and “Drawing Horizontal Lines” in the chapter “ Arbi^ 
trary Motions and Drawing Lines and (^aracters.” 

To reset the tab replacement character to a space, use the . t c request with no 
argument. Lines can also be drawn with the in-line \ 1 command, described in 
the chapter “Arbitrary Motions and Drawing Lines and Characters.” 
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Summary of the . t c Request 

Mnemonic: 

tab character 

Form if Request: 

. t c c 

Initial Value: 

Space 

^No Argument: 

Removed 

Explanation: 

The tab repetition character becomes c, or is removed, specifying motion. 

Notes: 

E (see Table A-2) 


Summary of Tabs The table below is a summary of the types of tab stops. There are three types of 

internal tab stops — fe/r-adjusting, rig/ir-adjusting, and centering. In the follow¬ 
ing table: 

D is the distance from the current position on the input line 

(where a tab was found) to the next tab stop. 

nextrstring consists of the input characters following the tab up to the next 
tab or end of line. 


W is the width of next^string. 

Table 6-1 Types of Tab Stops 


Tab 
letter ; 

Tab 

type 

Length of motion or 
repeated characters 

Location of 
nexustring 

blank 

Left ^ 

D 

Following D 

R 

Right 

D-W 

Right adjusted within D 

C 1 

Centered 

D-mn 

Centered on right end of D 
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Summary of the .t.a Request 

Mnemonic: 

tab 

Form of Request: 

.taATf... 

Initial Value: 

0.8 inches in nroff, 0.5 inches in troff. 

If No Argument: 

I^ored 

Explanation: 

Set tab stops and types—iV is the tab stop value and f is die type, troff 
tab stops are preset every 0.5 inches; nr of f tab stops are preset every 0.8 
inches. r=R means right-adjusting tabs, t=C means centering tabs, and if t is 
absent, the tabs are left-adjusting tab stops. Stop values in the list of tab 
stops are separated by spaces, and a value preceded by + is treated as an 
increment to the previous stop value. 

Notes: 

E, m (see Table A-2) 

6.2. Leaders — Repeated 
Runs of Characters 

Leaders are repeated runs of the same character between tab stops. Leaders are 
most often used to hang two separated pieces of text together. A common appli¬ 
cation is in tables of contents. If you look at the contents for this manual you 
will see that the chapter and section titles (on the left of the line) are separated 
from the page number (On the right end of the line) by a row of dots. In fact here 
is a short example to illustrate what the leaders look like: 


Contents 

2.0 Blunt Uses of Qubs . 

2.1 Social Qdbs . 

2.2 Arthritic Qubs . 

2.3 Golf Clubs . 

2.4 Two-by-Four Clubs 

. 13 

. 16 

.... 18 

. 25 

. 29 


The dots are called leaders, because they ‘lead’ your eye from one thing to the 
other. It is not nearly so easy to read stuff like that if the leaders aren’t there: 


Contents 


2.0 Blunt Uses of Qubs 

13 

2.1 Social Qubs 

16 

2.2 Arthritic Qubs 

18 

2.3 Golf Clubs 

25 

2.4 Two-by-Four Clubs 

29 


The leader character is normally a period, but it can in fact be any character you 
like — some people prefer dots and some people prefer a solid line: 
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Contents 


2.0 Blunt Uses of Qubs _ 13 

2.1 Social Qubs _ 16 

2.2 Arthritic Qubs __ 18 

2.3 Golf Qubs _ 25 

2.4 Two-by-Four Clubs __ 29 


A leader is very similar to a tab, but you get the repeated characters by typing an 
in-line \ a sequence instead of a tab or a \ t sequence. The \ a sequence is a 
control-A character or an ASCII SOH (start of heading) character and is hereafter 
known as the leader character for the purposes of this discussion. When the 
leader character is encountered in text it generates a string of repeated characters. 
The length of the repeated string of characters is governed by internal tab stops 
specified just as for ordinary tabs as discussed in the section on tabs above. The 
major difference between tabs and leaders is that tabs generate motion and 
leaders generate & string of periods. Let’s look at a fragment of the text that gen¬ 
erated the examples above: 



What we’re trying to get here are lines of text with the section numbers and the 
titles, followed by a string of leader characters, followed by some space and then 
the page number at the right-hand end of the line. Tables of contents tend to look 
better with shorter line lengths, so we set our first tab to five inches minus five 
en-spaces to leave a gap at the end of the leader. The second tab is set to a right¬ 
adjusting tab at five inches. Each line of the table now contains the text to appear 
on the left end, followed by a couple of spaces, followed by the \ a sequence to 
indicated the leader, followed by the \ t sequence to indicate the tab, and finally 
followed by the page number. The result of formatting all that stuff is: 


2.0 Blunt Uses of Qubs ..... 13 

2.1 Social Qubs ......... 16 

2.2 Arthritic Qubs ........ 18 

2.3 Golf Qubs ....... 25 

2.4 Two-by-Four Qubs .... 29 
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. Ic — Change the Leader 
Character 

Just as you could use the .tc request to change die character that gets generated 
with tabs, you can use the . I c (leader character) request to specify the character 
that is generated by a leader. The standard leader character is the period. We can 
show this by taking our last fragment and placing a . Ic request before it to 
change the leader character to an underline: 


1 .DS 

^ .1g _ set leader character 

.ta 5.Qi-5nR S.OiR set tabs 

2.0 Blunt Uses of Clubs \a\tl3" 

2.1 Social Clubs \a\tl6” 

2.2 Arthritic Clubs \a\tl8” 

2.3 Golf Clubs \a\t25” 

2.4 Two-b^r-Four Clubs \a\t29” 

.DE 

l .- V 

2.0 Blunt Uses of Qubs 

Then when we format the thing, it looks like this: 

13 

2.1 Social Qubs 

16 

2.2 Arthritic Qubs 

18 

2.3 Golf Qubs 

25 

2.4 Two-by-Four Clubs 

29 


Whereas the length of generated motion for a tab can be negative, the length of a 
repeated character string cannot be. Repeated character strings contain an integer 
number of characters, and any residual distance is added before the leaders as 
space. Tabs or leaders found after the last tab stop are igiored, but may be used 
as next-string terminators. 

Tabs and leaders are not interpreted in copy mode. \ t and \ a always generate a 
non-interpreted tab and leader respectively, and are equivalent to actual tabs and 
leaders in copy mode. 


Summary of the .iQ. Request 

Mnemonic: 

leader character 

Form 0 !f Request: 

. Ic c 

Initial Value: 

. 

If No Argument: 

Removed — successive \ as act like tabs 

Explanation: 

The leader repetition character becomes c, or is removed. Successive leader 
requests (\as) act like tabs. 

Notes: 

E (see Table A-2) 




u 
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6.3. . f c — Set Field 
Characters 


A field is a more general mechanism for laying out material between tab stops. 
Hardly anyone ever needs to use fields, but the tbl preprocessor uses tli em for 
placing tabular material on the page. This section is a very short discussion on 
how to use fields. In general, when you want to lay out tabular material you 
should use tbl to do the job for you. Fields are a way of reducing the r umber of 
tab stops you have to set, and also have trof f or nrof f do some automatic 
work in parceling out padding space for you. 

A field lives between the current position on the input line and the next tlab stop. 
The start and end of the field are indicated by a field delimiter character, trof f 
or nrof f places the field on the line and pads out any excess space witli spaces. 
You indicate where the padding actually goes by placing padding indica tor char¬ 
acters at various places in the field. You set the field delimiter character and the 
padding indicator character with the . f c (field characters) request hi tlie 
absence of any other informatiori, trof f or nrof f has the field mechanism 
turned off entirely. The . f c request looks like: 


.fc dp 


where d is the field delimiter character and p is the padding indicator cha racter. 

If you do not specify any character for a padding indicator, the space character is 
the default. However, this means that you could not have spaces within he field, 
so you normally specify the padding indicator as something other than a space. 

So let’s start with a very simple example of a single field and see what we get. 
Here is the input: 


/ -- - 

-ta 3.01 

set a single tab at three inches 


.fc # @ 

set field delimiter character to Hand 


! tab ! 

set padding indicator character to @ 

the ! characters show where tabs are 


tstring of characters# 

! tab ! 

the i characters show where tabs are 


• 

’ .. 


j 

and here is the output after formatting: 



string of characters 


This is not very exciting — the characters in the field are simply left-adjiisted in 
the field, and the rest of the field up to the tab stop are padded with space ?. You 
would get exactly the same result if you placed the padding indicator character at 
the right end of the field to indicate toat you wanted the padding on the ri ght - 
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/ 

.ta 3.01 

set a single tab at three inches 

. 

-fG # @ 

set field delimiter character to 4 


! tab ! 

set padding indicator character to @ 

the ! characters show where tabs are 


#string of Gharacters@# 

! tab I 

the ! characters show where tabs are 


: .fC 

V 




As you can see, the result is identical to the one just above: 

! ! 

string of characters 

! ! 


But now we can place a padding indicator character at the left end of the field 
and get strings right-adjusted in the field: 


r 


\ 

.ta 3.01 

set a single tab at three inches 


■ fc # @ 

set field delimiter character to 4 
set padding indicator character as @ 


! tab ! 

the / characters show where tabs are 


#@strlng of characters# 



#@another string of characters# 


! tab ! 

the ! characters show where tabs are 


; . f c 



V 


_/ 


We used two strings of different length here to show how they are right-adjusted 
against the tab stop: 

! ! 

string of characters 
another string of characters 
! ! 

You can see how the spaces were placed on the left end of the field because that 
is we where we placed the padding indicator character, and the strings got 
adjusted right to the tab stop. 


Then we can get fields centered by placing the padding indicator character at 
both ends of the string: 


r . 


\ 

.ta 3.01 

set a single tab at three inches 


.fc # e 

set field delimiter character to 4 


! tab ! 

set padding indicator character as @ 

the ! characters show where tabs are 


#@String of characters@# 

#@longer string of characters®# 


! tab ! 

the ! characters show where tabs are 


■ .fc 


_/ 


Again we used two strings of different lengths to show the effect of centering the 
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! 

String of characters 
string of characters 
\ 


! 

left string 
longer left string 
! 


! 


! 


string of characters 
longer string of characters 


! 



I 


In general, a field or a sub-field between a pair of padding indicator characters is 
centered in its space on the line. 

Things get even more useful when you have multiple sub-fields in a field — the 
padding spaces are then parceled out so that the sub-fields are uniformly left- 
adjusted, right-adjusted, or centered between the current position and the next tab 
stop: 


r 


\ 

.ta 5.01 

seta single tab at five inches 


.fc # @ 

setifield delimiter character to # 
set padding indicator character as(@ 


! tab ! 

use the ! characters to show where tabs are 


#String of 

characters# 


#string of 

characters©another string# 


! tcO) ! 

use the ! characters to show where tabs are 


V 


_/ 


and here is the output after we format that: 


! 


another string 

f 



And finally we can show three strings within a field, with the left part left- 
adjusted, the center part centered, and the right part right-adjusted: 

< —--- -— 

.ta 5.0i 
.fc # 0 
! tab t 

#left string0center String@right string# 

#longer left string©longer center string©longer right string# 

! tab ! 


and here is the output after we format that: 

! 

center string right string 

longer center string longer right string 

! 


So to summarize, a field is contained between a pair of field delimiter characters. 

A field consists of sub-fields separated by padding indicator characters. The field 
length is the distance on the input line from the position where the field begins to 
the next tab stop. The difference between the total length of all the sub-fields and 
the field length is incorporated as horizontal padding space that is divided among ( ) 

the indicated padding places. The incorporated padding can be negative. 
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Summary of the . fc Request 

Mnemonic: 

field character 

Form of Request: 

.fcfp 

Initial Value: 

Field mechanism is off 

If No Argument: 

Field mechanism is turned off. 

Explanation: 

Set the field delimiter to f, set the padding indicator to p (if specified) or to 
the ipacc character if p is not specified. In the absence of arguments, the 
field mechanism is turned off. 
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Titles and Page Numbering 


7.1. Titles in Page Headers 



This is an area where things get tougher, because tr o f f doesn’t do any of diis 
automatically. Of necessity , some of this section is a cookbook, to be copied 
literally until you get some experience. 

Suppose you want a title at the top of each page, saying just 

left top center top right top 

There was a very early text formatter called rojf, where you could say 

- ^ 

•he 'left top'center top'right top' 

.fo 'left bottom^ center bottom^ right bottom^ 

to get headers and footers automatically on every page. Alas, this doesn’t work 
in t rof f, which is a serious hardship for the novice. Instead you have to do a 
lot of specification: 

□ You have to say what the actual title is (reasonably easy — you just use the 
. 11 request to specify the title). 

□ You have to specify when to print die tide (also reasonably easy — you set a 
trap to cal a macro that actually does the work), 

n and finally you have to say what to do at and around the title line (this is the 
hard part). 


Taking these three things in reverse order, first we define a . NP macro (for new 
page) to process titles and the like at the end of one page and the beginning of the 
next: 




To make sure we’re at the top of a page, we issue a ‘begin page’ request 'bp, 
which skips to top-of-page (we’ll explain the' shortly). Then we space down 
half an inch (with the 'sp 0.51 request), and print die title (the use of . 11 
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should be self explanatory — later we will discuss the title parameters), space 
another 0.3 inches (with toe 'sp 0.3i request), and we’re done. 


To ask for . NP at toe bottom of each page, we have to say something like ‘when 
toe text is within an inch of toe bottom of the page, start toe processing for a new 
page’. This is done with a ‘when’ request. wh: 


r 



.wh —1: 

L NP 






See Chapter 10 for a more detailed description of toe . wh request. No dot (.) is 
used before NP in toe when request because in this case, we’re specifying toe 
name of a macro, not calling a macro. The minus sign means measure up from 
toe bottom of toe page, so ‘-li’ means one inch from the bottom. 

The . wh request appears in toe input outside toe definition of . NP ; typically toe 
input would be 


f -—-_ 

N 

. de NP 


definition of the NP macro 


.wh -li NP 



j 


Now what happens? As text is actually being output, troff keeps track of its 
vertical position on toe page. After a line is printed within one inch from toe bot¬ 
tom, toe . NP macro is activated. In toe jargon, the . wh request sets a trap at the 
specified place, which is ‘ sprung’ when that point is passed. . NP skips to toe top 
of toe next page (that’s what toe 'bp was for), then prints the title with toe 
appropriate margins. 

Why'bp and'sp instead of .bp and .sp? The answer is that .bp and .sp, 
like several other requests, break toe current line — that is, all the input text col¬ 
lected but not yet printed is flushed out as soon as possible, and toe next input 
line is guaranteed to start a new line of ouq)ut. If we had used . bp or . s p in toe 
. NP macro , a break would occur in the middle of toe current output line when a 
new page is started. The effect would be to print toe left-over part of that line at 
toe top of the page, followed by toe next input line on a new output line, some¬ 
thing like this: 

-—-—- 

last line but one at almost the bottom of the page 
last line at the bottom of the 

title on the bottom of the page 


page break 
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> 

title on the top of the next page 


page. 


L 



This is not what we want. Using' instead of . forarequesttells troff thatno 
break is to take place — the output line currently being Med should not be 
forced out before the space or new page. 

The list of requests that break lines is short and natural: 


Table 7-1 Requests timt Cause a Line Break 


Command 

Explanation 

.bp 

Begin a new page 

; .br 

Break the current output line 

: .ce 

Center line(s) 

.fi 

Start Ming text lines 

.nf 

Stop filling text lines 

• sp 

Space vertically 

.in 

Indent the left margin 

.ti 

Temporary indent the left margin for the next line only 


No odier requests break lines, regardless of whedier you use a . or a'. If you 
really do need a break, add a . br (break) request at the appropriate place. 


7.2. Fonts and Point Sizes One other thing to beware of — if you’re changing fonts or point sizes a lot, you 
in Titles may find that if you cross a page boundary in an unexpected font or size, your 

titles come out in that size and font instead of what you intended. Furthermore, 
the length of a title is independent of the current line length, so tides wiU come 
out at the default length of 6.5 inches unless you change it, which is done with 
the . It (lengfli of tide) request 



Summary of the . It Request 

Mnemonic: 

length of tide 

Form of Request: 

. It iN 

Initial Value: 

6.5 inches 

If No Argument: 

previous value 

Explanation: 

Set length of tide to ±A^. The line-length and the tide-length are/ndepen- 
dent. Indents do not apply to tides; page-offsets do. 

Notes: 

E, m (see Table A-2) 


There are several ways to fix the problems of point sizes and fonts in tides. For 


sun 
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the simplest applications, we can define the . NP macro to set the proper size and 
font for the title, then restore the previous values, like this: 


^ - 




.de 

NP 



'bp 




'sp 

0.5i 



.ft 

R 

\” set title font to Roman 


.ps 

10 

\” and size to 10 point 


.It 

6i 

\” and length to 6 inches 


.tl 

' left 

'center'right' 


•PS 


\” revert to previous size 


: .ft 

P 

\” and to previous forit 


'sp 

0.3i 



\ 



_/ 


This version of .NP does not work if the fields in the . tl request contain size or 
font changes. What we would like to do in cases like this is remember the status 
of certain aspects of the environment, change them to meet our needs for the time 
being, and then restore them after we’re done with the special stuff. This require¬ 
ment is satisfied by trof f ’s environment mechanism discussed in Chapter 17, 
Environments. 

To get a footer at the bottom of a page, you can modify . NP so it does some pro¬ 
cessing before the 'bp request, or split the job so that there is a separate footer 
macro invoked at the bottom margin and a header macro invoked at the top of the 
page. 

Output page numbers are computed automatically as each page is produced 
(starting at 1), but no numbers are printed unless you ask for them explicitly. To 
get page numbers printed, include the character % in the . 11 line at the position 
where you want the number to appear. For example 


r - 

I .tl 

A 


_> 


centers the page number inside hyphens. 


7.3. . pc — Page Number You can change the page number character with the . pc request. 
Character 



Summary of the . p c Request 

Mnemonic: 

page-rmmber character 

Form of Request: 

.pcc 

Initial Value: 

% 

If No Argument: 

Off 

Explanation: 

Set the page-number character to c, or remove it if there is no c argument. 

The page-number register remains %. 
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You can set the page number at any time with either . bp «, which immediately 
starts a new page numbered n, or with . pn n, which sete the page number for the 
next page but doesn’t skip to the new page. Again, . bp +« sets the page number 
to n more than its current value; .bp means .bp +1. 

7.4. .tl Request — Three The .tl (title) request automatically places three text fields at the left, center, 

Parameters and right of a line (with a title4ength specifiable via die . It (length of title) 

request The most common use for three-part titles is to put running headers and 
footers at the top and bottom of pages just like those in this manual. In fact, the 
. 11 request may be used anywhere, and is independent of the normal text col¬ 
lecting process. For example, we just placed a three-part title right here in the 
text: 


Hunting the Snark 

-85- 

by typing the a three-part title request that looks like: 

Smiles and Soap 


r 

i .tl 'Hunting the Snark'— % —'Smiles and Soap' 



<_^_ 



and you might notice that the page number in the formatted example is the same 
as the page number for this page. 


Summary of the . tl Request 

Mnemonic: 

title 

Form of Request: 

.tl ’left’center’right’ 

Initial Value: 

Nodiing 

If No Argument : 

Nothing 

Explanation: 

The strings in the left, center, and right fields are respectively left-adjusted, 
centered, and right-adjusted in the current title-length. Any of the strings 
may be empty, and overlapping is permitted. If the page-number character 
(initially %) is found within any of the fields it is replaced by the current 
page number having the format assigned to register %. Any character may 
be used as the string dehmiter. 
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t r o f f Input and Output... 89 
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t r o f f Input and Output 


We now describe two trof f requests that we omitted earlier, because dieir use¬ 
fulness is more apparent when you understand the trof f command line. Nor¬ 
mally t r of f takes its input from the files given when it is called up. However 
there are ways in which the formatter can be made to take part of its input from 
elsewhere, using trof f requests embedded in the document text. 

8.1. . s o — Read Text 
from a File 


r 


hostname% troff xoacros document 


hostname% 


V_ 



as we showed earlier, but it’s a bit of a nuisance having to do this aU the time. 
Also, if only some of our documents use the macros, and others don’t, it can be 
difficult to remember which is which. An alternative is to make the first line of 
the document file look like this: 


f 


\ .so macros 



J 


Now we can format the dociunent by: 



A 

hostname% troff document 


;hoStname % 


V_ ____ 

J 


The first thing trof f sees inthe file ifocM/nenr is the request .so macros 
which teUs it to read input from the file caled macros, A^en it finishes taking 
input from macros, trof f continues to read the original &&document. 

Another way of using the .so request lets you format a complete document, held 
in several files, by only giving one filename to the t r o f f command. Let us 
create a file called document containing: 


The . so request, which teUs trof f to switch over and take its source from the 
named file. For example, suppose you have a set of macros that you have 
defined, and you have them in a file called macros. We can call them up from 
the t r of f command line: 
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O 


We can now format it with the troff command line: 



This is a lot easier than typing all the filenames each time you format the docu¬ 
ment, and a lot less prone to error. 


This technique is especially useful if your filenames reflect the contents of the 
various sections, rather than the order in which they appear. For instance, look at 
this file which describes a whole book (something like the one you are reading): 


o 


It is obviously much easier to format the whole thing with a troff command 
line like this: 



than it would be if you had to supply all the filenames in the right order. Notice 
that we used the comment feature of troff to tie chapter titles to filenames. 


hostname% cat book 
.so bookmacros 
.so preface 
.so intro 

.so login \’^Getting Started on the UNIX System 

.so directs \”Directories and the File System 
.so stdio \"Commands, Processes, and Standard Files 

<etc.,.> 

.so biblio \"Bibliography 

hostname% 
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Summary of the . so Request 

Mnemonic: 

source 

Form of Request: 

. so filename 

Explanation: 

Switch source file — the top input (file reading) level is switched to 
filename. The soureed-in file is read directly and processed immediately 
when the . so line is encountered. When the new file ends, input is again 
taken from the original file. . sos may be nested. 


8.2. .nx — Read Next 
Source File 


Summary of the . Request 

Mnemonic: 

next 

Form cf Request: 

. nx filename 

If No Argument: 

end-of-file 

Explanation: 

Next file is ^/enomc. The current file is considered ended, and the input is 
immediately switched to filename. There is no return to the file containing 
the .nxcommand. 

8.3. Pipe Output to a 

Specified Program 
(nroff only) 

A couple of examples of programs you might want you pipe your n r o f f output 
to are Ipr and eol. Your source line might look like this: 

f .. N 

: .pi /usr/ucb/lpr 

<_^/ 

or 


.pi /usr/bin/col 

J 


if you had formatted tables in your source file. 

Summary of the .pi. Request 

Mnemonic: 

pipe 

Form cf Request: 

. pi programjtame 

Explanation: 

Rpe output to program (nro f f only). This request must occur before any 
printing occurs. No arguments are transmitted to program. 
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o 

8.4. . rd — Read from the Another t rof f request that switches input from the file you specify is the . rd 

Standard Input (read) request. The standard input can be the user’s keyboard, a pipe, or a file. 

The .rdrequestreads an insertion fiom the standard input. Whentroff 
encounters the . rd request, it prompts for input by sounding the terminal beU or 
flashing the screen. A visible prompt can be given by adding an argument to 
. r d, as we show in the example below. 


Everything typed up to a blank line (two newline characters in a row) is inserted 
into the text being formatted at that point. This can be used to ‘personalize ’ form 
letters. If you have an input file with this text: 



then when you format it, you will be prompted for input: 



After typing the name Peter you have to press the RETURN key twice, since 
t rof f needs a blank line to end input. The result of formatting that file is: 



To get another copy of this for Bill, you just run the t rof f command again: 
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Since troff takes input from the terminal up to a blank line, you are not limited 
to a single word, or even a single line of input. You can use this method to insert 
addresses or anything else into form letters. 


Summary of the .rdi Request 

Mnemonic: 

read 

Form of Request: 

.rdprompt 

Initial Value: 

Not applicable 

If No Argument: 

prompt=BEL 

Explanation: 

Read insertion from the standard input until two newlines in a row are 
found. Ifthe standard input is the user’s keyboard, (ora bel) is 

written onto the user’s terminal. . rd behaves like a macro, and arguments 
may be placed after prompt. Use the standard way to access arguments in 
macros (see Chapter 10. 


If insertions are to be taken from the terminal keyboard while output is being 
printed on the terminal, die command line option -q will turn off the echoing of 
keyboard input and prompt only with BEL. The regular input and insertion input 
cannot simultaneously come from the standard input. 

As an example, multiple copies of a form letter may be prepared by entering the 
insertions for aU the copies in one file to be used as the standard input, and caus¬ 
ing the file containing Ae letter to reinvoke itself using . nx (see the previous 
section); the process would ultimately be ended by a . ex in the insertion file. 
Example: 


r 


> 

Letter File 

Names File 


Dear . . . 

John 


.rd 

blank line 



Bill 



blank line 


.nx Letter 

.ex 


<_ 


J 


To put everything together, you could use; 





hostname% cat Names 

1 troff Letter 


v_ 
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8.5. . ex — Exit from 

nroff or troff 



Summary of the . Request 

Mnemonic: 

exit 

Form cf Request: 

.QK prompt 

Explanation: 

Exitfrom nroff or troff. Text processing is terminated exactly as if all 
input had ended. 



8.6. . tm — Send Messages 
to the Standard Error 
File 


The . tm (terminal message) request displays a message on the standard error 
file. The request looks hke: 


.tm tell me some good news 


and when troff or nroff encounters this in the input file, it displays the string 


< -- - - - 

\ 

tell me some good news 



___ y 


on the standard error file. This request has been used in older versions of the 
-ms macro package to rebuke the user when (for instance) an abstract for a paper 
was longer than a page. Other macro packages use the . tm request for assisting 
in generating tables of contents and indices and such supplementary material. 




Summary of the .tm Request 

Mnemonic: 

terminal message 

Form Of Request: 

.t.m string ■ 

Initial Value: 

Not applicable 

If No Argument: 

Display a newline 

Explanation: 

After skipping initial hlaiiks, string (rest of the line) is read in copy mode 
and written on the user’s terminal. 


o 
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9.1. . ds — Define Strings. 98 

9.2. .as — Append to a String. 99 

9.3. Removing or Renaming String Definitions. 101 



















Obviously if a paper contains a large number of occurrences of an acute accent 
over a letter ‘e’, typing \ o " e \ '" for each 6 would be a great nuisance. (See 
Chapter 12 for more detailed information on drawing lines and characters. 

Fortunately , tro f f provides a way that you can store an arbitrary collection of 
text in a string, and thereafter use the string name as a shorthand for its contents. 
Strings are one of several t r o f f mechanisms whose judicious use lets you type 
a document with less effort and organize it so that extensive format changes can 
be made with few editing changes. A reference to a string is replaced in the text 
by the string definition. 

A string is a named sequence of characters, not including a newline character, 
that may be interpolated by name at any point in your text. Note that names of 
t r of f requests, names of macros, and names of strings all share the same name 
list. String names may be one or two characters long and may usurp previously- 
defined request, macro, or string names. 

You create a string (and give it an initial value) with the . ds (define string) 
request You can later add more characters to the end of the string by using the 
.as (append to string) request. 


String names may be either one or two characters long. You get the value of a 
string placed in the text where it is said to be interpolated, by using the notation: 



for a two-character string named xx. 

String references and macro invocations may be nested. 
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o 

9.1. . ds — Define Strings You create a string (and define its initial value) with the . ds (define string) 

request. The line 



defines the string e to have the value \ o " e \ '" 

You refer to them with the sequence \ * x for one-character names or \ * ( xy for 
two-character names. Thus, to get tdldphone, given the definition of the string e 
as above, we can say f^*e]\*ephone. 

As another live example, in the section on ligatures in Chapter 5, Fonts and Spe¬ 
cial Characters, we noted that trof f doesn’t know about the Scandinavian 
ligamres — you have to decide for yourself how to define them. Here are our 
definitions of the strings for those ligatures: 



See the section entitled “\ h Function — Arbitrary Horizontal Motion" in 
Chapter 12 for a discussion on what the \ h constructs are doing in the string 
definitions above. Having defined the strings, all you have to do is type the 
string references like this: 




in order to get... the Scandinavian ligatures oe, m, CE, and M... into your 
stream of text. 


If a string must begin with spaces, define it as 



The double quote character signals the beginning of the definition. There is no 
trailing quote — the end of the line terminates the string. 

A string may actually be several lines long; if t r o f f encounters a \ at the end 
of any line, the backslash and the newline characters are disregarded resulting in 
the next line being added to the current one. So you can make a long string sim¬ 
ply by ending each line except the last with a backslash: 



Strings may be defined in terms of other strings, or even in terms of themselves. 
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Summary of the .<^s Request 

Mnemonic: 

define string 

Form of Request: 

.<3is XX string 

Initial Value: 

Not applicable 

If No Argument: 

Ignored 

Explanation: 

Define a string xx containing string. Any initial double-quote in string is 
stripped off to permit initial spaces. 

9.2. . as — Append to a 
String 

The . as (append to string) request adds characters to ifae end of a string. You 
use the . as request like this: 


f -^ 


.as XXstring-of^eharaeters 

^ ^ 

where string-of-eharacters is appended to the end of whatever is already in the 
string XX. 

Note that the string mentioned in a .as request is created if it didn’t already 
exist, so in that respect an initial . as request acts just like a . ds request. 

For example, here’s a short fragment from the . H macro that was used to gen¬ 
erate the section numbers in this document. The . H macro is called up like 

.Blevel-number "Text of the Title" 

_ / 

where level-number is 1,2,3,... to indicate that this is a first, second, 
third,... level heading. The . H macro keeps track of the various section 
numbers via a bunch of number registers HI through H5, and they are tested for 
and appended to the SN string if appropriate. For example: 
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ds SN \ \n (Hl. set the initial section number string 

if \\n(NS>l .as SN \\n(H2. append H2 if needed 
if \\n(NS>2 .as SN \\n{H3. append H3 if needed 
if \\n (NS>3 .as SN \\n (H4, appendH4 ^needed 
if \\n(NS>4 .as SN \\n(H5. append H5 if needed 


more processing to compute indentations and such 


\ \ * ( SN\ \ W \ t \ c Now output the text 


and yet more processing 


Let's unscramble that mess. The essential parts are the initial line that says: 



which sets the SN (section number) string to the value of the HI number register 
that counts chapter level numbers. Then the following four lines essentially aU 
perform a test that says: 


. if the level-number is greater than append the next higher sec¬ 

tion counter to the string. That is, if the current section number is 
greater than 2, we append the value of the level 3 counter, then if the 
section number is greater than 3, we append the value of the level 4 
counter, and so on. 


Finally, the built-up SN string, followed by the text of the title, gets placed into 
the ou^ut text with the lines that read: 



And in fact we can use the mechanisms that exist to play games like that because 
we are using a macro package to format this document, and those number regis¬ 
ters are available to us. So we can define a string like this: 



and interpolate that string like this: 



to get the value 
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9. 

printed in the text. Now we can append the rest of the section counters to that XX 
string like this (without earing whether they have any values): 



and then when we interpolate that string we get this: 
9.2.0.00. 


which, if you look, should be the section number of the stuff you are now read¬ 
ing. 


Summary of the . as Request 

Mnemonic: 

append to string 

Form (f Request: 

.as XXstring 

Initial Value: 

Not applicable 

If No Argument : 

Ignored 

Explanation: 

Append string to string xx (append version of . ds). The string xx is created 
if it didn’t already exist. 



9.3. Removing or Strings (just like macros) can be renamed with the . rn (rename) request, or can 

Renaming String be removed from the namelist with the . rm (remove) request. Refer to Chapter 

Definitions 10 for more detailed descriptions of the . rn and . rm commands. 


o 


^ mm 
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10.1. Macros 



. de— Define a Macro 



Before we can go much further in nrof f or trof f, we need to learn something 
about the macro facility. In its simplest form, a macro is just shorthand notation 
similar to a string. A macro is a collection of several separate t r o f f commands 
which, when bundled together, achieves (sometimes complex) formatting when 
the macro is invoked. Whereas a string is somewhat limited because its 
definition is specific, a macro can interpret arguments that can change its 
behavior from one invocation to the next. 

A macro is a named set of arbitrary lines that may be invoked by name or with a 
trap. Macros are created by . de and . di requests, and appended to by . am and 
. da requests; . di and . da requests cause normal output to be stored in a 
macro. A macro is invoked in the same way as a request; a control line beginning 
. XX interpolates the contents of macro xx. The remainder of the line may contain 
up to nine arguments. Request, macro, and string names share the name 
list. Macro names may be one or two characters long and may usurp previously- 
defined request, macro, or string names. String references and macro invocations 
may be nested. Any of these entities may be renamed with a . r n request or 
removed wifii a . rm request. 


Suppose we want every paragraph to start in exactly the same way — wifii a 
space and a temporary indent of two ems. We show a (very simplified) version 
of the . PP (paragraph) macro fi'om the -ms macro package; 


r 

> 

.sp 


.ti +2m 


V _ 



Then to save typing, we would like to coUapse these into one shorthand line, a 
troff ‘request’ like 
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with the . de (define) request: 


• de PP 
. sp 

.:ti +2m 


The first line names the macro (we used . PP) which is a standard macro notation 
for ‘paragraph’. It is common practice to use upper-case names for macros so 
that their names don’t conflict with ordinary trof £ requests. The last line . . 
marks the end of the definition, hi between the beginning and end of the 
definition, is the text (often called the replacement text), which is simply 
inserted whenever trof f sees the request or macro call 

-- ^ 

.PP 


The definition of . PP has to precede its first use; undefined macros are simply 
ignored. Names are restricted to one or two characters. 

Using macros for commonly-occurring sequences of requests is critically impor¬ 
tant. Not only does it save typing, but it makes later changes much easier. Sup¬ 
pose we decide that the paragraph indent should be greater, the vertical space 
should be less, and the font should be Roman. Instead of changing the whole 
document, we need only change the definition of the , PP macro to something 
like 


.de PP \" paragraph macro 
. sp 2p 
.ti +3m 
• ft R 


and the change takes effect everywhere we used , PP. 

The notation \ " is an in-line trof f function that means that the rest of the line 
is to be ignored. We use it here to add comments to the macro definition (a wise 
idea once definitions get complicated). 
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Summary of the . de Request 

Mnemonic: 

define 

Form of Request: 

.dexxyy 

Initial Value: 

Not applicable 

If No Argument: 

II 

Explanation: 

Define or redefine the macro xx. The contents of the macro begin on the 
next input line. Input lines are copied in copy mode \mtil the definition is 
terminated by a line beginning with . yy, whereupon the macro yy is called. 

In the absence of yy, the definition is terminated by a line beginning with 
‘. . ’ . A macro may contain . de requests provided the terminating macros 
differ or the contained definition terminator is concealed. ‘. . ’ can be con¬ 
cealed as \\. . which will copy as \. . andberereadas ‘ 


. rm — Remove Requests, 
Macros, or Strings 


Summary of the .Tm Request 

Mnemonic: 

remove 

Form cf Request: 

. rmxx 

Initial Value: 

Not applicable 

If No Argument: 

Ignored 

Explanation: 

Remove request, macro, or string. The name xc is removed from the name 
list and any related storage space is freed. Subsequent references will have 
no effect. 





Asun 
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. rn — Rename Requests, 
Macros or Strings 


Summary of the . r n Request 

Mnemonic: 

rename 

Form of Request: 

.rnxxyy 

Initial Value: 

Not apyplicable 

If No Argument: 

Ignored 

Explanation: 

Rename request, macro, or string xr to > 9 '. Ifyy exists, it is removed first. 


Refer to Chapter 9, Strings for information on defining strings. 

As another example of macros, ojnsider these two, which start and end a block of 
offset, unfilled text, like most of the examples in this paper: 


r 



A 

.de 

BS \" 

Start indented block 


. sp 




.nf 

. in 

. 3i 



• de 

BE \" 

end indented block 


; .sp 




i .fi 




. in 

-0.3i 








Now we can surround text like 


Copy to: 

John Doe 
Richard Roberts 
Stanley Smith 


by the requests .BS and . BE, and it will come out as it did above. Notice that 
we indented by an incremental amount: . in +0.3i instead of .in 0.3i. 
This way we can nest our uses of . BS and . BE to get blocks within blocks. 

If later on we decide that the indent should be half an inch, then it is only neces¬ 
sary to change the definitions of . BS and . BE, not the whole paper. 

Macros With Arguments The next step is to define macros that can change from one use to the next 

according to parameters supplied as arguments to the macro. To make this work, 
we need two things: first, when we define the macro, we have to indicate that 
some parts of it will be provided as arguments when the macro is called. Then 
when the macro is called we have to provide actual arguments to be plugged into 
the definition. 
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When a macro is invoiced by name, the remainder of the line can contain up to 
nine arguments. The argument separator is the space character, and arguments 
may be surrounded by double-quotes to permit embedded space characters. Pairs 
of double-quotes may be embedded in double-quoted arguments to represent a 
single double-quote. If the desired arguments won’t fit on a line, a concealed 
newline (\) may be used to continue the arguments on the next line. 

When a macro is invoked the input level is pushed down and any arguments 
available at the previous level become imavailable imtil the macro is completely 
read and the previous level is restored. A macro’s own arguments can be inter¬ 
polated at any point within the macro with \$N, which interpolates the iVth argu¬ 
ment (1^<9). If an invoked argument doesn’t exist, a null string results. For 
example, the macro xc may be defined by 



Note that the \ $ was concealed in the definition with a preceding backslash (\). 
The number of currently available arguments is in the . $ register. 

No arguments are available at the top (non-macro) level in this implementation. 
Because string referencing is implemented as an input-level push-down, no argu¬ 
ments are available from within a string. No arguments are available within a 
trap-invoked macro. 

Arguments are copied in copy mode oaXo a stack where they are available for 
reference. The mechanism does not allow an argument to contain a direct refer¬ 
ence to a long stiing (interpolated at copy time) and it is advisable to conceal 
string references (with an extra \) to delay interpolation until argument reference 
time. 

Let’s illustrate by defining a macro . SM that will print its argument two point 

sizes smaller than the surrounding text That is, the macro call 

-^ . 

'.SM UNIX 

< ___ ^ 

wiU produce UNIX. 

The definition of . SM is 
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r - 


.de SM 


\s-2\\$r\s+2 



_> 


Within a macro definition, the symbol \ \ $ « refers to the nth argument that the 
macro was called with. Thus \ \ $ 1 is the string to be placed in a smaller point 
size when . SM is called. 


As a slightly more complicated version, the following definition of . SM permits 
optional second and third arguments that will be printed in the normal size: 

( ---->, 

: .de SM 

■ \\$3\s-2\\$l\s+2V\$2 

-—_; 

Arguments not provided when the macro is called are treated as empty, so 

^ ^ ^ 

. SM UNIX ) , 

-—— -—_ — _ > 

produces 

UNIX), 

while 

- — ---^ 

.SM UNIX ). ( 

--- 

produces 

(UNIX). 


It is convenient to reverse the order of arguments because trailing punctuation is 
much more common than leading. 

The following macro . BD is the one used to make the ‘bold Roman’ we have 
been using for t r o f f request names in text It combines horizontal motions, 
width computations, and argument rearrangement. 


j . de BD 

\&\\$ 3\f1\\$1\h'-\w'\\$1'u+lu'\\$1\fP\\$2 


The \ h and \ w commands need no extra backslash, as we discuss in the section 
C 0 py Mode Input Interpretation. The \ & is there in case the argument begins 
with a period. 

Two backslashes are needed with the \ \ $ n commands, though, to protect one of 
them when the macro is being defined. Perhaps a second example will make this 
clearer. Consider a macro called . S H which produces section headings like the 
ones in this manual, with the sections numbered automatically, and the title in 
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bold in a smaller size. The use is 


f -^- 

\ 

1 .SH ’’Seetion title ...” 

V.. ....... 

j 


If the argument to a macro is to contain spaces, then it must be surrounded by 
double quotes, unlike a string, where only the leading quote is permitted. 

Here is the definition of the . SH macro: 


f - 



.nr 

SH 0 initialize section number 


.de 

SH 


.sp 

0.3i 


.ft 

B 


.nr 

SH \\n(SH+l\” increment number 


.ps 

Wn tPS-l decrease PS 


Wn 

(SH. \\$1 V” number, title 


-ps 

\\n(PS restore PS 


1 .sp 

0.3i 


.ft 

R 


V 




The section number is kept in number register SH, which is incremented each 
time just before it is used. A number register may have the same name as a 
macro without conflict but a string may not. 

We used \\n (SH instead of \n (SH and \\n (PS instead of \n (PS. If we had 
used \n ( SH, we would get the value of the register at the time the macro was 
defined, not at the time it was called. If that’s what you want, fine, but that isn’t 
the ease here. Similarly, by using \\n (PS, we get flie point size at the time the 
macro is called. 

As an example that does not involve numbers, recall our . NP macro which had: 


—____ . 


.tl 'left'center'right' 

L . . . 


We could make these into parameters by using instead 


r 

.tl '\\.*(LT'\\*(CT'\\*( 

N 

c _ 

J 


so the title comes from three strings called LT, CT and RT for left title, center 
title, and right title, respectively. If these are empty, then the title will be a blank 
line. Normally CT would be set with something like 


r 

A 

.ds CT - % - 


v__ _ 

J 


to give just the page number between hyphens, but a user could supply private 
definitions for any of the strings. 
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. am — Append to a Macro 


Summary of the . am. Request 

Mnemonic: 

append to macro 

Form of Request: 

.amxxyy 

Initial Value: 

Not applicable 

If No Argument: 


Explanation: 

Append to macro xx (append version of . de). 


Copy Mode Input During definition and extension of strings and macros (not by diversion) the 

Interpretation input is read in copy mode. The input is copied without interpretation except 

that: 


□ The contents of number registers indicated by \n are interpolated. 

□ Strings indicated by \* are interpolated. 

a Arguments indicated by \ $ are interpolated. 

□ Conceded newlines preceded by backslash (\ newline) are eliminated. 

□ Comments indicated by \ " are e liminate d 

□ \ t and \ a are interpreted as ASCII horizontal tab and SOH respectively (see 
Chapter 6, Tabs, Leaders, and Fields for more information). 

□ W is interpreted as \ 

□ \ . is interpreted as "." 

These interpretations can be suppressed by adding another \ (backslash) to the 
beginning of the command. For example, since \ \ maps into a \, \ \n will copy 
as \n which will be interpreted as a number register indicator when the macro or 
string is reread. 

10.2. Using Diversions to There are numerous occasions in page layout when it is necessary to store some 
Store Text for Later text for a period of time without actually printing it. Footnotes are the most 

Processing obvious example: the text of the footnote usually appears in the input well 

before the place on the page where it is to be printed is reached. In fact, the place 
where it is output normally depends on how big it is, which implies that there 
must be a way to process the footnote at least enough to decide its size without 
printing it. 

troff provides a mechanism called a diversion for doing this processing. A 
diversion is very similar to a macro and in fact uses the same mechanisms as the 
macro facility. Any part of the output may be sent into a diversion instead of' 
being printed, and then at some convenient time the diversion may be brought 
back into the input. 


A 
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. di — Divert Text 


The request . di xy begins a diversion — all subsequent output is eolleeted into 
tile diversion called xy until a . di request with no argument is encountered, 
which tenninates the diversion. The processed text is available at any time 
thereafter, simply by giving the request: 



The vertical size of tiie last finished diversion is contained in the built-in number 
register dn. 


As a simple example, suppose we want to implement a ‘keep-release’ operation, 
so that text between the requests . KS and . KE will not be split across a page 
boundary (as for a figure or table). Clearly, when a . KS is encoimtered, we have 
to begin diverting the output so we can find out how big it is. Then when a . KE 
is seen, we decide wlrether the diverted text will fit on the current page, and print 
it either there if it fits, or at the top of the next page if it doesn’t. So: 


f . 





' .de 

KS 

\" 

start keep 


-br 


\" 

start fresh line 


.ev 

1 

\" 

collect in new environment 


.fi 


'V" 

make it filled text 


1 .di 

XX 

\" 

collect in XX 


.de 

KE 

\" 

end keep 


.br 


\" 

get last partial line 


i 


\" 

end diversion 


.if 

\\n(dn>=\\n(.t .bp \” bp if doesn't fit 


I .nf 


\" 

bring it back in no-fill 


.XX 


\" 

text 


; .ev 



return to normal environment 


\_ 






Recall that number register nl is the current position on the output page. Since 
output was being diverted, this remains at its value when tiie diversion started, 
dn is the amount of text in the diversion; . t (another built-in register) is the dis¬ 
tance to the next trap, which we assume is at the bottom margin of the page. If 
the diversion is large enough to go past tiie trap, the . if is satisfied, and a . bp 
is issued. In either case, the diverted output is then brou^t back with It. xx. 
trof f will do no further processing on it 

This is not the most general keep-release, nor is it robust in the face of all con¬ 
ceivable inputs, but it would require more space than we have here to write it in 
full generdity. This section is not intended to teach everything about diversions, 
but to sketch out enough that you can read existing macro packages with some 
comprehension. 

Processed output may be diverted into a macro for purposes such as footnote pro¬ 
cessing or determining the horizontal and vertical size of some text for condi¬ 
tional changing of pages or columns. A single diversion trap may be set at a 
specified vertical position. The number registers dn and dl respectively contain 
the vertical and horizontal size of the most recently ended diversion. 
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Processed text that is diverted into a macro retains the vertical size of each of its 
lines when reread in nofiU mode regardless of the current V. Constant-spaced 
(. c s) or emboldened (. bd) text that is diverted can be reread correctly only if 
these modes are again or stiU in effect at reread time. One way to do tWs is to 
embed in the diversion the appropriate . g s or . bd requests with the ‘tran¬ 
sparent’ mechanism described in the chapter Introduction to nroff and troff. 

Diversions may be nested and certain parameters and registers are associated 
with the current diversion level (the top non-diversion level may be thought of as 
the 0th diversion level). These are the diversion trap and associated macro, no¬ 
space mode, The internally-saved marked place (see . mk and . rt ), the current 
vertical place (. d register), the current high-water text baseline (, h register), and 
the current diversion name (. z register). 


Summary of the . (IL Request 

Mnemonic: 

divert 

Form cf Request: 

. di XX 

Initial Value: 

Not applicable 

If No Argument: 

End of diversion 

Explanation: 

Divert output to macro xx. Normal text processing occurs during diversion 
except that page offsetting is not done. The diversion ends when the request 
. di or . da is encountered without an argument; extraneous requests of this 
type should not appear when nested diversions are being used. 

Notes: 

D (see Table A-2) 


. da — Append to a Diversion 



Summary of the . da Request 

Mnemonic: 

append to diversion 

Form of Request: 

• daxc 

Initial Value: 

Not applicable 

If No Argument: 

End of diversion 

Explanation: 

Append to diversion xx. This is the diversion equivalent of the . am (append 
to macro) request. 


10.3. Using Traps to Three types of trap mechanisms are available, namely traps, diversion 

Process Text at traps, and input-line-count traps. 

Specific Places on a . 

Page Macro-invocation traps may be planted using the . wh (when) request at any page 

position including the top. This trap position may be changed using the . ch 
(change) request. Trap positions at or below the bottom of the page have no 
effect unless or until moved to within the page or rendered effective by an 
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increase in page lengtti. 

Two traps may be planted at the same position only by first planting them at dif¬ 
ferent positions and then moving one of the traps; the first planted trap will con¬ 
ceal the second unless and until the first one is moved. If the first one is moved 
back, it again conceals the second trap. 

The macro associated with a page trap is automatically invoked when a line of 
text is ou^ut whose vertical size reaches or ‘sweeps p£^t’ the trap position. 
Reaching the bottom of a page springs the top-of-page trap, if any, provided there 
is a next page. 

The distance to the next trap position is available in the . t register; if there are 
no traps between the ciurent position and the bottom of the page, the distance 
returned is the distance to the page bottom. 

A macro-invocation trap effective in the current diversion may be planted using 
the . dt (diversion trap) request. The .t register works in a diversion; if there is 
no subsequent trap a large distance is returned. For a description of input-line- 
coimt traps, see the . it request below. 


. wh — Set Page or Position 
Traps 


Summary of the . wh Request 

Mnemonic: 

when 

Form (^Request: 

.^f^hNxx 

Initial Value: 

Not applicable 

If No Argument: 

Not applicable 

Explanation: 

Install a trap to invoke xx at page position N; a negative N is interpreted 
with respect to the page bottom. Any macro previously planted at N is 
replaced by xc. A zero N refers to the top of a page. In the absence of xx, 
the first-fotmd trap at N, if any, is removed. 

Notes: 

V (see Table A-2) 
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. ch — Change Position of a 
Page Trap 



Summary of the . ch. Request 

Mnemonic: 

change trap 

Form of Request: 

.chxxN 

Initial Value: 

Not applicable 

If No Argument: 

Not applicable 

Explanation: 

Change the trap position for macro xc to be iV. In the absence of N, the trap, 

- if any, is removed. 

Notes: 

V (see Table A-2) 


. dt — Set a Diversion Trap 


Summary of the . dt Request 

Mnemonic: 

diversion trap 

Form of Request: 

• dtNxc 

Initial Value: 

Not applicable 

If No Argument: 

Turn off diversion trap 

Explanation: 

Install a diversion trap at position N in the current diversion to invoke macro 

XX. Another . dt win redefine the diversion trap. If no arguments are 
given, the diversion trap is removed. 

Notes: 

D, v (see Table A-2) 


. it — Set an Input-Line 
Count Trap 



Summary of the . tt Request 

Mnemonic: 

input-line-count trap 

Form of Request: 

.LtNxx 

Initial Value: 

Not applicable 

If No Argument: 

Turn off trap 

Explanation: 

Set an input-line-count trap to invoke the macro xc after N lines of text input 
have been read (control or request lines don’t count). The text may be in¬ 
line text or text interpolated by in-line or trap-invoked macros. 

Notes: 

E (see Table A-2) 
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Set the End of 
Processing Trap 


Summary of the .em Request 

Mnemonic: 

end macro 

Form cf Request: 

.emxx 

Initial Value: 

Not applicable 

If No Argument: 

No trap installed 

Explanation: 

Can the macro xx when ail input has ended. The effect is the same as if the 
contents of xr had been at the end of the last file processed. 


sun 
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Number Registers 


In a programmable text formatter such as t ro f f, you need a facility for storing 
numbers somewhere, retrieving the numbers, and for doing arithmetic on those 
numbers, trof f meets this need by providing things called number registers. 
Number registers give you the ability to define variables where you can place 
numbers, retrieve the values of the variables, and do arithmetic on those values. 
Number registers, like strings and macros, can be useful in setting up a document 
so it is easy to change later. And of course number registers serve for any sort of 
arithmetic computation. 

Number registers, just like strings, have one- or two-character names. They are 
set by the . nr (number register) request, and are referenced anywhere by \ n x 
(one-character name) or \ n ( (two-character name). When you access a 
number register so^that its value appears in the printed text, the jargon says that 
you have interpolated Has. valiM of tiie number register. 

A variety of parameters are available to the user as predefined, named number 
registers (see Appendix D). In addition, users may define their own named regis¬ 
ters. Register names are one or two characters long and do not conflict with 
requesti^ macro, or string names. Except for certain predefined read-only regis¬ 
ters, a number register can be read, written, automatically incremented or decre¬ 
mented, and interpolated into the input in a variety of formats. One common use 
of user-defined registers is to automatically number sections, paragraphs, lines, 
etc. A number register may be used any time numerical input is expected or 
desired and may be used in numerical expressions. 

trof f defines several pre-defined number registers listed in Appendix D. 
Among them are % for the current page number, n l for the current vertical posi¬ 
tion on the page, dy, mo^ and yr for the current day, month and year (see Table 
D-1) for a complete list); and .s and .f for the current size and font—thefont 
is a number from 1 to 4. Any of these number registers can be used in computa¬ 
tions like any otiier register, but some, like . s and . f, cannot be changed with a 
. nr request because they are “read only” (see Table D-2) for a complete list)* 

11.1. . nr — Set Number You create and modify number registers using the . nr (number register) request. 

Registers In its simplest form, the . nr request places a value into a number re^ster—the 

register is created if it doesn’t already exist. The . nr request specifies the name 
of the number register, and also specifies the initial value to be placed in fliere. 

So tile request 
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o 



would be a request to set a register called PD (which we might know as ‘Para¬ 
graph Depth’ if we were writing a macro package) to the value 1.5v (1.5 of 
trof f’s vertical units). 


As an example of the use of number registers, in the -ms macro package, most 
significant parameters are defined in terms of the values of a handful of number 
registers (see the chapter “Formatting Documents with the -ms Macros” in For¬ 
matting Documents). These include the point size for text, the vertical spacing, 
and the line and title lengths. To set the point size and vertical spacing for the 
following paragraphs, for example, a user may say: 



The paragraph macro . pp is defined (roughly) as follows: 



This sets the font to Roman and the point size and line spacing to whatever 
values are stored in the P S and VS number registers. 


Why are there two backslashes? When trof f originally reads the macro 
definition, it peels off one backslash to see what’s coming next. To ensure that 
another is left in the definition when the macro is used, we have to put two 
backslashes in the definition. If only one backslash is used, point size and verti¬ 
cal spacing will be frozen at the time the macro is defined, not when the macro is 
used. 

Protecting by an extra layer of backslashes is only needed for \n, %*, \ $, and \ 
itself. Things like \ s, \ f, \ h, \ v, and so on do not need an extra backslash, 
since they are converted by trof f to an internal code immediately upon being 
seen. 
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Summary of the .nr Request 

Mnemonic: 

number register 

Form of Request: 

.nrR±NM 

Initial Value: 

Not applicable 

If No Argument: 

Ignored 

Explanation: 

Assign the value ±N to number register R, with respect to the previous 
value, if any. Set the increment for auto-incrementing to M. 

Notes: 

u (see Table A-2) 


11.2. Auto-Increment When you set a number register with the . nr request, you can also specify an 

Number Registers additional number as an auto-increment value — that is, the number is added to 

the number register every time you access the number register. You specify the 

auto-increment value wifli a request such as: 

--- , 

.nr sn 0 1 

V_ " - 

to specify a (hypothetical) section number register that starts off with the value 0 
and is incremented by 1 every time you use it. This might be applicable (for 
instance) to numbering the sections of a document automatically — something 
you might expect a computer to do for you. You might also define a numbered 
list macro that would clock up the item number every time you added a new list 
item. 

Here’s a very quick and dirty example of the use of auto-incrementing a number 
register: 

--- —— 

.nr cn —1 2 


the odd numbers \n+ (cn, \n+ (cn, \n+ (>cn, \n+ (cn, \n+ (cn, \n+ (cn. 



When we format the above sequence, we get the following: 
... the odd numbers 1,3,5,7,9,11,... 


The table below shows the effects of accessing the number registers x and xx 
after a . nr request that sets them to the value W with an auto-increment value of 
M. 
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Table 11-1 Access Sequences for Auto-incrementing Number Registers 



Access 

Sequence 

Effect on 
Register 

Value 

Interpolated 

.nr X N M 

\nx 

none 

N 

.nr XX N M 

\n(xx 

none 

N 

.nr X N M 

\n-i-x 

X incremented by M 

N+M 

.nr X N M 

\n-x 

X decremented by M 

N-M 

. nr XX N M ; 


XX incremented by M 

N+M 

: .nr XX N M 


XX decremented by Af 

N-M 


11.3. Arithmetic 

Expressions with 
Number Registers 


Arithmetic expressions can appear anywhere that a number is expected. As a 
trivial example. 


.nr PS \\n{PS-2 


decrements the value in the PS macro by 2. 


Expressions can use the arithmetic operators and logical operators as shown in 
the table below. Parts of an expression can be surrounded by parentheses. 



Table 11-2 Arithmetic Operators and Logical Operators for Expressions 


Arithmetic Operator 

Meaning 

+ 

Addition 

- 

Subtraction 

/ 

Division 

♦ 

Multiplication 

% 

Modulo 

Logical Operator 

Meaning 

< 

Less than 

> 

Greater than 

<= 

Less than or equal to 

>= 

Greater than or equal to 

= or = = 

Equal to 

St 

and 

• 

or 


Except where controlled by parentheses, evaluation of expressions is left-to-right 
—there is no operator precedence. 


n 
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11.4. 


.af — Specify 
Format of Number 
Registers 


Although the arithmetic we have done so far has been straightforward, more 
complicated things are somewhat tricky. First, number registers hold only 
integers, tr off arithmetic uses truncating integer division. Second, in the 
absence of parendieses, evaluation is done from left to right without any operator 
precedence (including relational operators). Thus 

7*T4^T3/13 

becomes ‘-1 ’. Number registers can occur anywhere in an expression, and so 
can scale indicators like p* i, m, and so on (but no spaces). Although integer 
division causes truncation, each number and its scale indicator is converted to 
machine units (1/432 inch) b^ore my arithmetic is done, so li/2u evaluates to 
0.5i correctly. 

The scale indicator u often has to appear where you would not expect it—in 
particular, when arithmetic is being done in a context that implies horizontal or 
vertical dimensions. For example, \ 

—. V 

.11 7/2i 

___ ——— ^ 

would seem obvious enough — 3,5 inches. Sorry — remember that the default 
units for horizontal parameters like the . 11 request are ems. So that expression 
is reaUy ‘7 ems / 2 inches’, and when translated into machine units, it becomes 
zero. How about 

--- 

.11 71/2 

^ ^ ----- ^ 

Still no good — the ‘2’ is ‘2 ems’, so ‘7i/2’ is small, allhough not zero. You 
must use 


/- 



! -1 

I 71/2u 


V_ 


J 


So again, a safe rule is to attach a scale indicator to every number, even con¬ 
stants. 


For aritiunetic done within a . nr request, there is no implication of horizontal or 
vertical dimension, so the default units are ‘units’, and 7i/2 and 7i/2u mean flie 
same thing. Thus 


r 


.nr 11 71/2 


.11 \\n(llu 


^^_ 

J 


does just what you want, so long as you don’t forget the u on the . 11 request. 


When you use a number' register as part of the text, the contents of the register 
are said to be interpolated into the text at that point. For example, you could use 
the following sequence: 
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.nr xy 567 

the value of the \fIxy\fP number register is: \n(xy. 



and when you formatted that sequence, it would appear as: 
... the value of the xy number register is: 567. ... 


When interpolated, the value of the number register is read out as a decimal 
number. You can change this format by using the . af (assign format) request to 
get things like Roman numerals or sequences of letters. Here is the example of 
the auto-incrementing section above, to with the interpolation format now set 
for lower-case Roman numerals: 

( ~ --> 

.nr cn —12 

.af cn i 

the odd Roman numerals \n+(cn, \n+(cn, \n+(cn, \n+(cn, \n+(cn, \n+(cn. 


When we format the above sequence, we get the following: 

... the odd Roman numerals i, iii, v, vii, ix, xi,... 

A decimal format having IV digits specifies a field width of W digits. 

Read-only number registers and the width function are always decimal. 

The table below shows the different formats you can apply to a number register 
when it is interpolated. 



Table 11-3 Interpolation Formats for Number Registers 


Format 

Description 

Numbering 

Sequence 

1 

decim^ 

0,1, 2, 3,4,5, ... 

001 

decimal with leading zeros 

OOG, 001, 002, 003,004,005,... 

... i 

lower-case Roman numerals 

0 , 1 , ii, iii, iv, v,... 

I 

upper-case Roman numerals ; 

0,1, II, III, IV, V,... 

a 

lower-case letters 

0, a, b, c,... aa, ab,... aaa,... 

A 

upper-case letters 

0, A, B, C,... AA, AB,... AAA,... 
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Summary of the . SlI Request 

Mnemonic: 

assign format 

Form of Request: 

. af /? c 

Initial Value: 

Arabic 

If No Argument: 

Ignored 

Explanation: 

Assign format c to register R. 


11.5. . r r — Remove If you ereate many number registers dynamically, you may have to remove 

Number Registers number registers that you aren’t using any more to recapture internal storage 

space for newer registers. You remove a number register with die . rr (remove 
register) request: 


( -- 

A 

- rr xy 



. j 


removes the number register from die list. 


Summary of the . r r Request 

Mnemonic: 

remove register 

Form of Request: 

.rr/? 

Initial Value: 

Not af^lieable 

If No Argument: 

Ignored I 

Explanation: 

Remove register R. If many registers are being created dynamically, it may 
become necessary to remove no-longer-used registers to recapture internal 
storage space for newer registers. 
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Drawing Lines and Characters 


This section is a grab-bag of functions for moving to arbitrary places on the page 
and for drawing titings. This section covers a number of useftil topics: 

□ Local motions — how to move forward and backward and up and down on 
the page to get special effects. 

□ Constructing whole characters out of pieces of characters that are available 
in the special font—these facilities are for doing mathematical typesetting. 

m Drawing horizonml and vertical lines to make boxes and underlines and 
such. 

□ Various types of padding characters, zero-width characters, and functions for 
obtaining &e width of a character string. 

Most of these commands are strai^tforward, but messy to read and tough to type 
correctly. 

12.1. \ u and \ d Functions If you can’t or don’t want to use eqn, subscripts and superscripts are then most 

— Half-Line Vertical easily done witii the half-line local motions \u (for up) and \ei (for down). To 

Movements move up the page half a point, insert a \u at flie desired place, and to go down 

the page half a point, insert a \d at the desired place. The \u and \d in-line 
functions should always be used in pairs, as explained below. Thus if your input 
consists of the following fragment: 



the output when that fragment is formatted consists of: 


... area of a circle is ‘ Area = tot’ when calculating ... 

This is a first approximation of what you want, but the superscript ‘2’ is too 
large. To make tiie‘2’smaller, bracket it with \s-2...\s0. This reduces the 
point-size by two points before the superscript and restores the point-size to the 
previous value after the superscript. This example input: 



when formatted, generates: 



131 
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2 

... area of a circle is ‘Area = Tcr ’ when calculating... 

Now the reason that the \u and \d functions should always be correctly paired is 
that they refer to the current vertical spacing, so you must be sure to put any 
local motions either both inside or both outside any size changes, or you will get 
an unbalanced vertical motion. Carrying this example further, the input could 
look like this: 

/-—-V 

I . . . area of a circle is 'Area = \(*pr\u\s-22\d\s0' when calculating . . 

V---/ 

We’ll format that example in a larger point-size so that you can see the effect of 
the baseline being out of whack. So when we format the above construct with 
the motions incorrectly paired, we get this: 

... area of a circle is ‘Area = Jtr^’ when calculating ... 

As you can see, the baseline is higher after the incorrectly-displayed equation. 

The next two sections describe the in-line \ v (vertical) and the \ h (horizontal) 
local motion functions. The general form of these functions is \ v 'N ' for die 
vertical motion function, and \ h 'N ' for the horizontal motion function. The 
argument W in the functions is the distance to move. The distance N may be 
negative — the positive directions are to the right mA down. 

A local motion is one contained within a line. To avoid unexpected vertical 
dislocations, it is necessary that the net vertical local motion within a word in 
filled text, and otherwise within a line, be zero. 

\ V Function — Arbitrary Sometimes the space given by \ u and \ d is not the right amount (usually too 

Vertical Motion much). The in-line \ v function reouests an arbitrarv amount of vertical motion 


moves up or down the page by the amount specified in amount. For example, 
here’s how to get a large letter at the start of a verse: 


-in +.31 
.ti -.31 

\v'1.0'\s36A\sO\v'-1.0'\h'-4p'wake! for Morning in the Bowl of Night 
\h'2p'Has flung the Stone that puts the Stars to Flight: 

.in “.3i 

And Lo! the Hunter of the East has caught 
The Sultanas Turret in a Noose of Light. 


and when we format that verse we get: 


Sometimes the space given by \ u and \ d is not the right amount (usually too 
much). The in-line \ v function requests an arbitrary amount of vertical motion. 
The in-line \v function 

y---—---- 

\ v ' amount 

^ -- J 


12.2. Arbitrary Local 
Horizontal and 
Vertical Motions 
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\h Function — Arbitrary 
Horizontal Motion 
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A wake! for Morning in the Bowl of Night 

kHas flung the Stone that puts the Stars to Flight: 
And Lo 1 the Hunter of the East has caught 
The Sultan’s Turret in a Noose of Light.^ 


The indent amount we used here (0.3 inch) was determined by fiddling around 
tmtil it looked reasorable. Later we show another in-line function for measuring 
the actual width of something. 

A minus sign means upward motion, while no si^ or a plus sign means move 
down the page. Thus \ v'-l' means an upward vertical motion of one line space. 

There are many other ways to specify the amount of motion. The following three 
examples are all legal. 

-\ 

\v'0.1i' 

Wsp' 

\v'—0.5m’ 

_ ^ _ /' 

Notice that the scale specifier (i, p, or m) goes inside the quotes. Any character 
can be used in place of the quotes; this is also tme of aH other trof f commands 
described in this section. 

Since trof f does not take within-the-line vertical motions into account when 
figuring out where it is on the page, output lines can have unexpected positions if 
the left and right ends aren’t at the same vertical position. Thus \ v, like \u and 
\d, should always balance upward vertical motion in aline with the same 
amount in the downward direction. 


Arbitrary horizontal motions are also available — \h is quite analogous to \v, 
except that the default scale factor is ems instead of line spaces. As an example. 


— 



o 

1 

-H 


_ 


_ J 


causes a backward motion of a tenth of an inch. As a practical matter, consider 
printing the mathematical symbol *»’. The standard spacing is too wide, so 


eqn replaces this by 


r 

1 >\h'-0.3m'> 


V_ 

J 


to produce ». 

Frequently \h is used with the width function, \w, to generate motions equal to 
the widfli of some character string. The construction 


^ Omar Khayyam — the Rubaiyat 


»sun 
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/- ——- 

\w' thing' 

A 


_ J 


is a number equal to the width of ‘thing’ in machine units (1/432 inch). All 
troff computations are ultimately done in these units. To move horizontally 
the width of an ‘x’, we can say 


\h'\w'x'u' 

^_ __ > 

As we mentioned above, the default scale factor for aU horizontal dimensions is 
m (ems), so here we must have the u for machine units, or the motion produced 
wiU be far too large, t ro f f is quite happy with the nested quotes, by the way, 
so long as you don’t leave any out. 


As a live example of this kind of construction, the oe,«, CE, and /E ligatures dis¬ 
cussed in the section on ligatures in the chapter Fonts and Special Characters, 
were constructed using the \h fimction to define the following strings: 


f - 




"N 

.ds 

ae 

a\h'-(\w'a'u*4/10) 

' e 


.ds 

Ae 

A\h'-(\w'A'u*4/l:0) 

'E 


.ds 

oe 

o\h'-(\w'o'u*4/10) 

' e 


.ds 

Oe 

0\h'-{\w'0'u*4/lG) 

'E 

_ ; 


and for any given one Of those strings, the mess is unscrambled like this: 


Construct 

Explanation 

.ds ae 

Define a string called‘ae’. 

a 

Letter ‘a’ in the string. 

\h'- (\wra' u*4/10 ) ' 

Move backward 0.4 of the width of the letter ‘a’. 

1 

Letter ‘ e’ in the string. ; 


12.3. \0 Function— Thein-line \0 functionisanunpaddable white spaceof the same width as a 

Digit-Size Spaces digit. ‘Unpaddable’ means that it will never be widened or split across a line by 

line justification and filling. You could use the digit space to get numerical 
columns correctly lined up. For example, suppose you have this list of items: 


I 
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f 


A 

.nf 



.ta 

5n 


Step Description 


. sp 5p 


1. 

Unpack the handy dandy fuse blower. 


2. 

Inspect for obvious shipping defects. 


9. 

Find a wall socket. 


10. 

Insert handy dandy fuse blower in wall socket. 


: 11. 

Push red button to blow all fuses. 


.fi 



V_ 


J 


When you format this list of operations, you get fliis result: 


Step Description 

1. Unpack the handy dandy fuse blower. 

2. Inspect for obvious shipping defects. 

9. Find a wall socket. 

10. Insert handy dandy fuse blower in wall socket. 

11. Push red button to blow all fuses. 

As you can see, the numbers do not line up at the decimal point, but instead are 
lined up on the left. Racing a space character in front of the digits in the input is 
not sufficient measure to line up the digits at the decimal. A space is not the 
same width as a digit (at least not in trof f). A solution is to use the unpad- 
dable digit-space character \ 0 in front of the single digits like this: 


( -- 



N 

1 .nf 




;.ta 5n 




Step 

VODescription 



. sp 5p 




\ 01. 

Unpack the handy dandy fuse blower. 


CM 

O 

Inspect for obvious 

shipping defects. 


\09. 

Find a wall socket. 



10. Insert handy dandy fuse 

blower in wall socket. 


i 11. Push red button to blow 

all fuses. 


1 .fi 




V_ 



V 


Now when you format the text, you get this result: 


^sun 
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Step Description 

1. Unpack the handy dandy fuse blower. 

2. Inspect for obvious shipping defects. 


9. Find a wan socket. 

10. Insert handy dandy fuse blower in wall socket 

11. Push red button to blow aH fuses. 

which looks better than the previous example. 


12.4. ‘\ ’ Function — 
Unpaddable Space 


12.5. \ I and \ " Functions 
— Thick and Thin 
Spaces 


There is also the indine \ function, which is the \ character (backslash) followed 
by a space character. This function is an unpaddable character the width of a 
space. You can use this to make sure that things don’t get split across line boun¬ 
daries, for instance if you want to see something like nr of f -Tip n^fik in 
the stream of text, withthe command line set off like it was here and ensuring 
that it all appears on one line, you would type it in as 
\ \ \f(LBnroffX -Tlp\fP\ \fImyfile\fP\ \ 
in-line in the text. 


In typography, there are times when you need spaces that are one^sixth or one- 
twelfth of the width of an em-space. t rof f supplies the in-line \ | fiinction 
which is one-sixth of an em-space wide — this is sometimes called a ‘thick 
space’. Where woidd you want such a thing? Well one place it could be used is 
in making an ellipsis look better. In general, an ellipsis in a proportional font 
looks too cramped if you just string three dots together: 



and so the answer is often to use the thick space to get a more pleasing effect like 
this: 



Lastly, the in-line \ " function is one-twelfth of the width of an em-space space. 
This function is almost always used for a typographical application caled italic 
correction. Consider an italic word followed by some punctuation such as do 
tetl\ Because the italic letters are slanted to the right, they lean slightly on the 
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trailing punctuation, especially when the last letter is a tall one like the I in tiie 
example. So, what typographers do is to apply the italic correction in the form of 
a thin space just before the punctuation, so &at the effect is now do tell ! What 
we actually typed here was 


r 

\ \fIdo tellVfPX'^! 

\ 


v 


with tile italic coireetion just before the exclamation mark. 

Typing the italic correction at every instance of adjacent Roman and italic text, 
would be alot of work. Some macro packages constmct special-purpose macros 
for applying the italic correction. For example, the -man macro package has a 
. IR macro tiiat joins alternating italic and Roman words together so that you can 
italicize parts of words or have italic text with trailing Roman punctuation. You 
use the . IR macro like: 


r - 

A 

.IR well spring 



J 


to get the composite effect of wc//spring in your text. The . IR macro (some¬ 
what simplified) looks like this: 

-----s 

.de IR 

\«\fI\\$l\"\fR\\$2\fI\\$3\'\fR\\$4\fI\\$5\'\fR\\$6\fI\\$7V'\fR\\$8\fI\\$9\-\fR 

__ / 

and you can see the italic correction applied after every parameter that is set in 
the italic font. 


12.6. \ & Function — Non- The \ & function is a character that does not print, and does not take up any space 

Printing Zero-Width in the ou^ut text. You might wonder what use it is at aU? One application of 

Character the non-printing character used throughout this manual is to display examples of 

text containing trof f or nrof f requests. To print a trof f request just as it 
appears in the input, you have to distinguish it from a real t r of f request. You 
cannot print an example whose input looks just like this: 

( - 

i .in +0.5i indent the text half an inch 


lots of lines of text to be pro cessed 


.in -0.5i unindent the te:U half an inch 

s_/ 


The . characters at the beginning of each line would be interpreted as t r of f 
requests instead of text representing examples of requests. In such cases, we 
have to use the \ & function to stop t rof f or nr off from interpreting the . at 
the start of the line as a control character. We would type the example like this: 
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Another place where the \ & function is useful is within some of the other in-line 
functions such as the \ 1 function. The \ 1 function draws lines and you type the 
function like: 



where length is the length of the line you want to draw, and character is the char¬ 
acter to use. Sometimes, the character might look like a part of length, for 
instance. 



doesn’t get you a one-inch line of = signs as you might expect, because the = 
sign looks like an expression where you are trying to say that “1 .Oi is equal to” 
something else. When you encounter this situation, type the \ 1 function like 
this: 



and the result is a one-inch line of =========== signs as you see here. 


12.7. \ o Function — Automaticaliy-centered overstriking of up to nine characters is possible with the 

Overstriking in-line \o (overstrike) function. The Vo function looks like \o ' string' where 

Characters die characters in jtnng are overprinted with their centers aligned. This means for 

example, that you can print from one to nine different characters superimposed 
upon each other, trof £ determines the width of this “character” you are creat¬ 
ing to be the width of the widest character in your string. The superimposed 
characters are then centered on the widest character. The string should not con¬ 
tain local vertical motion. The in-line Vo function is used like this: 



This is useful for printing accents, as in 
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which produces 


systfeme tdldphonique 

The accents are \ (ga (grave accent) and \ (aa (acute accent), or \' and \ '; 
remember ttiat each is just one character to trof f. 


/- 

\ 

\o"e\/" 



j 

produces 


6 


and 


r 


\o”\ (inoVCsl” 


< _ 

j 


produces 

4. 


12.8. \ z Function — Zero You can make your own overstrikes with another special convention, \ z, the 
Motion Characters zero-motion command. \ z x suppresses the normal horizontal motion after 

printing the single character x, so another character can be laid on top of it. 
Although sizes can be changed within \ o> trof f centers the characters on the 
widest of them, and there can be no horizontal or vertical motions, so \ z may be 
the only way to get what you want: 


is produced by 


f - 

\ 

.sp 2 


\s8 \z\(Gi\sl4\z\ (ci\s22\z\(ciVsS 6\z\ (ci 

j 


The .sp 2 line is needed to leave enough vertical space for the result. 
As another example, an extra-heavy semicolon that looks like 


; instead of ; or 

can be constructed with a big comma and a big period above it: 



where 0.2 5m is an empirical constant 
As ftirther examples, \z \ (ci\ (pi produces 
© 
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and \ (br \ z\ (rn\ (ul\ (br produces the smallest possible constructed box; 

D 

There is also a more general overstriking function for piling things up vertically 
— this topic is discussed in the section “ \b Function — Build Large Brackets” 
later in this chapter. 


12.9. \ w Function — Get Back in the section on using tabs, we saw how we could set tab stops to various 

Width of a String positions on the line md lay stuff out in colrunns based on the tab stops. Some¬ 

times it is hard to figure out where the tab stops should go because you can’t 
always teU in advance how wide things are —this is especially true for propor- 
tiond fonts (by definition the characters aren’t all the same size). Often what you 
want is to set tab stops based on the width of an item. Then you can set tab stops 
based on that width and remain independent of the size of the characters if you 
decide to change point size. 

The in-line width function \ w ' string ' generates the numerical width of string 
(in basic units). For example, .ti -\w'l. 'u could be used to temporarily 
indent leftward a distance equal to the size of the string ‘ 1. ’. Size and font 
changes may be safely embedded in string, and do not affect the current environ¬ 
ment. 

In a previous example we showed how a large capital letter coifid be placed in a 
verse with vertical motions and we played some games with indenting to get the 
thing to come out more-orTess right. The problem with that approach is that we 
had to measure the size of the character and arrive at the indent by trial and error 
(actually, error and trial). Another problem is that the measured indent didn’t 
take the point-size into account — if we decide to change sizes, the measure¬ 
ments are aU wrong. The width function can measure the size of the thing 
directly, so here’s our example aU over again using the \ w function: 

, --- ___ - ^ 

.in +\w'\s36A\sO'u 
-ti -\w'\s36A\sO'u 

■ \v'1.0'\s36A\sO\v'-1.0'\h'-5p'wake! for Morning in the Bowl of Night 
; Ah'lp'Has flung the Stone that puts the Stars to Flight: 

.in —Vw'\ s36A\sO'u 

And Lo! the Hunter of the East has caught 
The Sultan's Turret in a Noose of Light. 


and when we format that text we get this result: 

Awake! for Morning in the Bowl of Night 
xV Has flimg the Stone that puts the Stars to Flight: 

And Lo ! the Hunter of the East has caught 
The Sultan’s Turret in a Noose of Light. 

The width function also sets three number registers. The registers st (string top) 
and sb (string bottom) are set respectively to the highest and lowest extent of 
string relative to the baseline; then, for example, the total height of the string is 
\n ( stu-\n {sbu. In trof f the number register ct (character type) is set to a 
value between G and 3: 
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Table 12-1 trof f Width Function — et Number Register Values 


ct Number 
Register 
Value 

Meaning 

0 

aU of the characters in 
string were short lower 
ease characters without 
descenders (like e) 

1 

at least one diaracter has a 
descender (like y) 

2 

at least one character is tall 
(like H) 

3 

both taH characters and . 
characters with descenders 
are present. 


12.10. \ k Function — The in-line \ kx function stores the current horizontal position in the input line 

Mark Current into register x. As an example, we could get a bold italic effect by the constmc- 

Horizontal Place tion: 

f --s 

\kKWord \h' I \nxu+2u'word 

V_> 

This emboldens word by backing up to its absolute (hence, the I) beginning 
(Nkxwc>rd\h'l\nxu) plus 2 machine units (+2u) and overprinting it, resulting in 

word 
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12.11. \b Function — 
Build Large 
Brackets 


The Special (mathematical) font contains a number of characters for constructing 
large brackets out of pieces. The table below shows the escape-sequences for the 
individual pieces, what they look like, and their names. 


Table 12-2 Pieces for Constructing Large Brackets 


Escape 

Sequence 

Character 

Description 

\(lt 

r 

left top of big curly bracket 

\(lb 

i 

left bottom of big curly bracket 

\{rt 

ii 

right top of big curly bracket 

\(rb 

j 

right bottom of big cuily bracket 

\(lk 

i 

left center of big curly bracket 

\(rk 

1 

right center of big curly bracket 

\(bv 

1 

bold vertical 

\(lf 

1 

left floor (left bottom of big square bracket) 

\(rf 

j 

right floor (right bottom of big square bracket) 

\(le 

r 

left ceiling (left top of big square bracket) 

\{rc 

1 

right ceiling (right top of big square bracket) 


These pieces can be combined into various styles and sizes of brackets and 
braces by using the in-line \b (for bracketing) function. The \b function is used 
like this: 

--:-^ 

\b 'string ' 


to pile up the characters vertically m. string with the first character on top and the 
last on the bottom. The characters are vertically separated by one em and the 
total pile is centered 1/2-em above the current baseline (1/2-line in nrof f). For 
example: 

------- , 

\x' -0.5m' \x'0.5m' \b' \(lc\(If'E\r\b' \(rc\(rf' 


produces 


E 


As with previous examples, we should unscramble the whole 


mess for you: 
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Escape 

Sequence 

Character 

Description \ 

\b 


start bracketing function 

\ (Ic 

r 

left ceiling 

: \ (if 

L 

left floor 

i E 


letter E 

\h 


start bracketing function 

\ (rc 

1 

right ceiling 

; \ (rf 1 

j 

right floor 


Here’s another example of using braces and brackets. You get this effect: 

[-)} 

by typing this: 

-—- 

\b'\(at\(lk\(lb' \b'\(lc\(lf' X \b'\(rc\(rf' \b'X (rt\(rk\ (rb' 
___ ^ 



12.12. \r Function — 
Reverse Vertical 
Motions 

12.13. Drawing Horizontal 
and Vertical Lines 


The \ r function makes a single reverse motion of one em upward in trof f, 
and one line upward in grof f. 

Typesetting systems commonly have commands to draw horizontal and vertical 
lines. Of course typographers don’t call them lines — they are called ‘rules’ 
because once upon a time they were drawn with rulers, t r of f provides a con¬ 
venient facility for drawing horizontal and vertical lines of arbitrary length with 
arbitrary characters, and these facilities are described in the subsections folow- 
ing. 


\1 Function — Draw The in-line \1 (lower-case ell) function draws a horizontal line. For example, 

Horizontal Lines the function \ 1'1.0 i ' draws a one-inch horizontal line like this 

_in the text. 

The line is actually drawn using the baseline rule character in t r o f f, and the 
underline character in nxof f, but you can in fact make the character that draws 
the Mne any character you like by placing the character after the length designa¬ 
tion. For example, you could draw a two inches of tildes by using \ 1'2,0 i ~' to 

in the text. The construction \ L is entirely 
analogous, except that it draws a vertical line instead of horizontal. 


The general form of the \1 function is 


( - 

\1 ' length character ^ 

.. N 

V_ 

.. ... J 
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\L Function 
Lines 


\/ 


where length is the length of the string of characters to be drawn, and character 
is the character to use to draw the line. If c/iaracter looks like a continuation of 
length, you can insulate character from length with the zero-width \ & sequence. 
If length is negative, a backward horizontal motion of size length is made before 
drawing the string. Any space resulting from length/ (size of character) having a 
remainder is put atthebeginning (left end) of the string. In the case ofcharacters 
that are (tesigned to be connected such as baseline-rule (_), underrule (_), and 
root-en ( ), the remainder space is covered by overlapping. If length is less than 
the width of character, a single character is centered on a distance length. As an 
example, here is a macro to underscore a string: 



to yield underlined words in the stream of text. You could also write a macro to 
draw a box arotmd a string: 


. de b x 

\(br\\$l\(br\ l'|0\(rn'\ lM0\(ul" 
---; 


and SO you can type: 
— 

.bx "words in a box" 


to get some [words in a box! in the text stream. 


Draw V ertical The in-line \ L (upper-case ell) function draws a vertical line. As in the case of 

the \ 1 function, the general form of the function is 

t -- 

\ L ' length character’ 


This draws a vertical line consisting of the (optional) character c/iaracfer stacked 
vertically apart 1 em (1 line in nrof f), with the first two characters overlapped, 
if necessary, to form a continuous line. The character is the box rule, 

| ( \ (br); the other suitable character is the 1 ( \ (bv). The line 

is begun without any initial motion relative to the current base line. A positive 
length specifies a line drawn downward and a negative length specifies a line 
drawn upward. After the line is drawn no compensating motions are made; the 
instantaneous baseline is at the end of the line. 
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Combining the Horizontal n 

and Vertical Line Drawing 

Functions _____ 

The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The zero- 
width box-rule and the Vi-em wide underrule were designed to form comers when using one-em vertical spacings. 
For example the macro 

■ de eb 

.sp —1 \"compensate for next automatic baseline spacing 

.nf \"avoid possibly overflowing word buffer 

\h.5n'\L ' I \\nzu-l '\1' \\n(.lutln\(ul' \L 1 \\nzu+l'\1' |Ou-.5n\(ul' 

\"draw box 

-fi 

draws a box around some text whose beginning vertical place was saved in number register z (using . mk z) as done 
for this paragraph. 


12.14. . me— Place 

Characters in the 
Margin 


Many types of documents require placing specific characters in the margins. The 
most common use of this is placing bars down the margins to indicate what’s 
changed in a document from one revision of a document to the next. This para¬ 
graph and the remainder of the text in this section were preceded by a 


.me \sl2\(br\s0; 

-\ 

k_ 

__ J 


request (that is, place a 12-point box-mle character in the margin) to turn on die 
marginal bars, and followed by a simple 


f 

\ 

.me 


^ -.- 



request to turn off the marginal bars. 

Currently, this request is not bug-free, and the margin character only appears to 
the ri^t of the ri^t margin, but not in left margins. Also, you’ll notice that the 
marginal bars do not appear on incomplete lines, such as this one. 


wsu.n 
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Summary of the .me Request 

Mnemonic: 

margin character 

Form cf Request: 

. me c N 

Initial Value: 

Not applicable 

If No Argument: 

Turn off margin characters 

Explanation: 

Specifies that a margin character c appear a distance N to the right of the 
right margin after each non-empty text line (except those produced by . 11). 

If the output line is too long (as can happen in nofiM mode) the character is 
appended to the line. If N is not given, the previous N is used; the initial N 
is 0.2 inches in nrof f and 1 em in trof f. 

Notes: 

E, m (see Table A-2) 
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Character Translations 


13.1. Input Character 
Translations 


13.2. . ec and . eo — Set 
Escape Character or 
Stop Escapes 


The newline delimits input lines. In addition, STX, ETTi;, ENQ, ACK, and BEL are 
accefH;ed, and may be used as delimiters or translated into a graphic with a . t r 
(translate) request (refer to the section entitled . t r -rr Output Translation^ All 
others are ignored. 

The escape character \ introduces escape sequences — meaning the following 
character is something else, or indicates some function. A complete list of such 
sequences is given in a later chapter. The \ character should not be confused 
with the ASCII control character ESC of the same name. The escape character 
can be changed with an . e c (escape character) request, and aU that has been said 
about the default \ becomes true for tiie new escape character. \ e can be used to 
print whatever the current escape character is. If necessary or convenient, tiie 
escape mechanism can be turned off with an . e o (escape ofO request and 
restored with the . ee request. 


Summary of the . eo Request 

Mnemonic: 

escape character 

Form of Request: 

. ec c 1 

Initial Value: 


If No Argument: 

\ 

Explanation: 

Set escape character to \, or to c, if given. 


Summary of the . eo Request 


Mnemonic: 

Form of Request: 
Initial Value: 

If No Argument: 
Explanation: 


escape mechanism off 
.eo 

Escape mechanism is on 
Turn escape mechanism off. 
Turn escape mechanism off. 
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13.3. . cc and . c2 — Set 
Control Characters 

Both the control character . and the control character ' may be 

changed, if desired. Such a change must be compatible with the design of any 
macros used in the span of the change, and particularly of any trap-invoked mac¬ 
ros. 

Summary of the . c c Request 

Mnemonic: 

control character 

Form 0 Request: 

,ccc 

Initial Value: 

. 

If No Argument: 

1 

Explanation: 

Set the basic control character to c, or reset to ‘ . ’. 


Summary of the . q2 Request 

Mnemonic: 

no-break control character 

Form 0 Request: 

. c2 c 

Initial Value: 

./ 

If No Argument: 

V 

Explanation: 

Set the no-break control character to c, or reset to ‘ ' 

13.4. . t r — Output 
Translation 

One character can be made a stand-in for another character using the . t r 
(translate) request. All text processing (for instance, character comparisons) 
takes place with the input (stand-in) character that appears to have the width of 
the final character. The graphic translation occurs at the moment of ou^ut 
(including diversion). 

Summary of the .tT Request 

Mnemonic: 

translate 

Form 0 Request: 

.tT abed _ 

Initial Value: 

Not Applicable 

If No Argument: 

No translation 

Explanation: 

Translate a into b, c into d, etc. If an odd number of characters is given, the 
last one is mapped into the space character. To be consistent, a particular 
translation must stay in effect from input to output time. 

Notes: 

0 (see Table A-2) 


Asun 
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Automatic Line Numbering 


14.1. . nm — Number 
Output Lines 

3 

6 

9 



Output lines may be numbered automatically via the . nm (munber) request. 
Refer to die following table for a summary of the .nm request. When in 
effect, a three-digit, Arabic number and a digit-space begins each line of 
output text. The text lines are thus offset by four digit-spaces, and otherwise 
retain their line length. To keep the ri^t margin aligned with an earlier 
margin, you may want to reduce the line length by the equivalent of four 
digit spaces. Blank lines, other vertical spaces, and lines generated by . 11 
are not numbered. Numbering can be temporarily suspended with die . nn 
(no number) request (see below), or with an . nm followed by a later , nm 
-H 0. In addition, a line number indent I, and the number-text separation S 
may be specified in digit-spaces. Further, it can be specified that only those 
line numbers that are multiples of some number M are to be printed (the oth¬ 
ers will appear as blank number fields). 


Summary of the .rm Request 

Mnemonic: 

numbering 

Form of Request: 

.nm±iVMiS'/ 

Initial Value: 

Line numbering turned off. 

If No Argument: 

Line numbering turned off. 

Explanation: 

Turn on line numbering if ±N is given. The next output line numbered is 
numbered ±N. Default values are M= 1, 5= 1, and 1= 0. iV is the line 
number counter (or incrementer if you use ±N), M is the multiple of the 
numbered lines to be printed on the page, S is the spacing between line 
numbers and text, and I is the amount of indent for the line numbers. 

Parameters corresponding to missing arguments are unaffected; a non¬ 
numeric argument is considered missing. In the absence of all arguments, 
numbering is turned off; the next line number is preserved for possible 
further use in number register In. 

Notes: 

E (see Table A-2) 
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14.2. . nn — Stop 

Numbering Lines 

When you are using the . nm request to munber lines (as discussed above), you 
can temporarily suspend the numbering with the . nn (no number) request. 


Summary of the . ViV\ Request 

Mnemonic: 

no numbering 

Form of Request: 

. nn IV 

Initial Value: 

Not applicable 

If No Argument: 

N=\ 

Explanation: 

The next N text output lines are not numbered. 

Notes: 

E (see Table A-2) 



As an example, the paragraph portions of this chapter are numbered with 
15 M=3: .nm 1 3 was placed at the beginning of the chapter, . nm was 

placed at the end of the first paragraph; and . nm + 0 was placed in front of 
this paragraph; and . nm finadly placed at the end. Line lengths were also 
18 changed (by \ w '0000 ' u) to keep the right side aligned. 


21 


Another example is 


. mm 5 5x3 


which turns on numbering with the line number of the next line to be 5 
greater than the last-numbered line, M= 5, spacing S is untouched, and with 
the indent / set to 3. 
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15.1. 



Conditional Requests 


.if — Conditional 
Request 


Suppose we want the . S H macro to leave two extra inches of space just before 
section 1, but nowhere else. The cleanest way to do that is to test inside the . S H 
macro whether the section number is 1, and add some space if it is. The . if 
request provides the conditional test that we can add just before the heading line 
is output: 

--- 

^ .if \\n(SH=l .sp 2i \" first section only 


The condition after the . if can be any arithmetic or logical expression. If the 
condition is logically true, or arithmetically greater than zero, the rest of the line 
is treated as if it were text — here a request. If the condition is false, or zero, or 
negative, the rest of the line is skipped. 

It is possible to perform more than one request if a condition is true. Suppose 
several operations are to be done before section 1. One possibility is to define a 
macro . SI and invoke it if we are about to do section 1 (as determined by a 
.if). 



r 



.if \\n(SH=l N 

- processing for section 1 -\} 


_ 


J 


The braces \ { and \} must occur in the positions shown or you will get unex¬ 
pected extra lines in your output, t r o f f also provides an ‘ if-else’ construction, 
which we will not go into here. 

A condition can be negated by preceding it with !; we get the same effect as 
above (but less clearly) by using 
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/ - 


.if !\\n(SH>l .SI 


V . _ _ 

... J 


There are a handful of other conditions that can be tested with .if. For exam¬ 
ple, is the current page even or odd? 


Y - 




. if e 

.tl 

''even page title'' 


; . if o 

.tl 

''odd page title'' 


V_ - 



j 


gives facing pages different titles when used inside an appropriate new page 
macro. 


Two other conditions are t and n , which tell you whether the formatter is 
troff or nroff. 


r— - 


.if t troff stuff _ 


.if n nroff stuff ... 

V 

Finally, string comparisons may be made in an .if: 

r 


.if 'stringl'string2' stuff 


V 

y 


does ‘stuff’ if stringl is the same as sfrmg2. The character separating the strings 
can be anything reasonable that is not contained in either string. The strings 
themselves can reference strings with \ *, arguments with \ $, and so on. 

In the following table, c is a one-character, built-in condition name, ! signifies 
not, N is a numerical expression, string! and string2 are strings delimited by any 
non-blank, non-numeric character not in the strings, and anything represents 
what is conditionally accepted. 


»sun 
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Summary of the .It Requests 

Mnemonic Jif, if-else, else 

Form of Request: 

Initial Value: 

If No Argument: 

Explanation 

. if c anything 

Not Applicable 

Not Applicable 

If condition e tme, accept anything as input. In multi-line case use \{:any- 
thingX}:. 

Form of Request: 

Explanation 

.if \c anything 

If condition c false, accept anything. 

Form of Request: 

Explanation 

. it N anything 

If expression N > 0, accept anything. 

Form of Request: 

Explanation 

• if \N anything 

If expression N < 0, accept anything. 

Form of Request: 

Explanation 

.if ' string! 'string2 ' anything 

If stringl identical to string!, accept anything. 

Form of Request : 

Explanation 

.if !' stringl ’string! ’ anything 

If stringl is not identical to string!, accept any thing. 

Form of Request: 

Explanation 

. ie c anything 

If portion of if-else (like above i f forms). 

Form of Request: 

Explanation 

. el anything 

Else portion of if-else. 


The built-in condition names are; 



Table 


15-1 


Built-In Condition Names for Conditional Processing 


Condition 

Name 

Truelf 

0 

Current page number is odd 


Current page number is even 

t 

! Formatter is troff 

n 

Formatter is n r o f f 
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15 . 2 . 


15 . 3 . 


If the condition c is trae, or if the number JV is greater than zero, or if the strings 
compare identically (including motions and character size and font), anything is 
accepted as input. If a ! precedes the condition, number, or string comparison, 
the sense of the acceptance is reversed. 

Any spaces between the condition and the beginning of anything are skipped 
over. Tht anything can be either a single input line (text, macro, or whatever) or 
a number of input lines. In the multi-line case, the first line must begin with a 
left delimiter \ { and the last line must end with a right delimiter \}. 

The request . ie (if-else) is almost identical to .if except that the acceptance 
state is remembered. A subsequent and matching . el (else) request then uses 
the reverse sense of that state, .ie - .el pairs may be nested. Refer to the 
Summary of the .iffor summaries of .ie and .el. 


Some examples are: 


/- 


.if e .tl ' Even Page 


V 

J 


which outputs a tide if the page number is even; and 


r - 


A 

. ie 

\n%>l \{\ 


' sp 

0.5i 


.tl 

' Page %''' 


1 ^ sp 

1.2i \} 


1 .el 

.sp ~ 2.5i 




_/ 


which treats page 1 differendy from other pages. 


• i g — Ignore Input Another mechanism for conditionally accepting input text is via the . i g (ignore) 

Text request Basically, you place the . ig request before a block of text you want to 

ignore: 

- - ^ - —— - 

. ig start of ignored block of text 


block of text you don’t want to appear in the printed output 


. . end of ignore block signalled with . . 

-—___i 

The . ig request functions like a macro definition via the . de request except 
that the text between the , ig and the terminating . . is discarded instead of 
being processed for printing. 

You can give the . ig request an argument—that is, an 


. ie and . el — If- 
Else and Else 
Conditionals 
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o 



You can of course combine the . ig request wifli the otier conditionals to ignore 
a block of text if a condition is satisfied. For example, you might want to omit 
blocks of text if the printed p^es are destined for different audiences: 
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Summary of the . ig Request 

Mnemonic: 

ignore 

Form cf Request: 

.igyy 

Initial Value: 

Not applicable 

If No Argument: 

Ignore text up to a line starting with . . 

Explanation: 

Ignore input lines up to and including a line starting with .3^ — use. .if 
no argument is specified on the request. . ig behaves exactly like the . de 
(define macro) request except that the input is discarded. The input is read 
in copy mode, and any auto-incremented number registers will be affected. 
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Debugging Requests. 165 

16.1. , pm — Display Names and Sizes of Defined Macros. 165 

16.2. . f 1 — Flush Ouq)ut Buffer... 166 

16.3. . ab — Abort. 166 












Debugging Requests 


troff and nro ff resemble languages for programming a typesetter rather than 
a mechanism to describe how a dociunent should be put together. There are 
times when you just can’t figure out why things are going wrong and not generat¬ 
ing results as advertised. The requests described here are for dyed-in-the-wool 
macro wizards. 


16.1. . pm — Display The . pmi (print macros) request displays the names of aU defined macros and 

Names and Sizes of how big they are. Why would anybody want to do such a thing? Well, if you’re 

Defined Macros using a macro as a diversion, you might find out (by printing its size) that it is far 

bigger than you expect (that it’s swallowing your entire file). 


Summary of the . Request 

Mnemonic: 

print macros 

Form of Request: 

.pm t 

Initial Value: 

Not applicable 

If No Argument: 

All 

Explanation: 

Print macros. The names and sizes of all of the defined macros and strings 
are printed on the user’s terminal; if t is given, only the total of the sizes is 
printed. The sizes are given in btocfa of 128 characters. 
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16.2. . f 1 — Flush Output 
Buffer 

The . f 1 (flush) request flushes the output buffer—this can be used when you’re 
using nrof f interactively. 

Summary of the . f 1 Request 

Mnemonic: 

flush 

Form of Request: 

.fl 

Initial Value: 

Not applicable 

If No Argument: 

adjusting is turned off 

Explanation: 

Flush output buffer. Used in interactive debugging to force output. 

16.3. . ab — Abort 

A final useful request in the debugging categoiy is the . ab (abort) request which 
basically bails out and stops the formatting. 

Summary of the . ab Request 

Mnemonic: 

abort 

Form of Request: 

. ab text 

Initial Value: 

Not applicable 

If No Argument: 

No text is displayed 

Explanation: 

Displays text and terminates without further processing. If rm is missing, 

‘User Abort’ is displayed. Does not cause a break. The output buiffer is 
flushed. 
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Environments. 169 

17.1. . ev — Switch Environment. 169 


o 













17.1. 



Environments 


. ev — Switch 
Environment 


As we mentioned, there is a potential problem when going across a page bound¬ 
ary: parameters like size and font for a page title may well be different from 
those in effect in the text when the page boundary occurs, t ro f f provides a 
very general way to deal with this and similar situations. There are six environ¬ 
ments, each of which has independendy-settable versions of many of the parame¬ 
ters associated with processing, including size, font, line and title lengths, 
fiU/nofiU mode, tab stops, and even partially-collected lines. Thus the titling 
problem may be readily solved by processing the main text in one environment 
and titles in a separate one with its own suitable parameters. 

The command . ev n shifts to environment n; n must be in the range 0 through 2. 
A . ev command with no argument returns to die previous environment. 
Environment names are maintained in a stack, so calls for different environments 
may be nested and unwound consistently. 

When trof f starts up, environment 0 is the default environment, so in general, 
the main text of your document is processed in this environment in the absence 
of any information to the contrary. Given this, we can modify the .NP (new 
page) macro to process titles in environment 1 like diis: 


f - 

i .de 

.ev 

NP 

1 

\” shift to new environment 


I -It 

6i 

\” set parameters here 


1 .ft 
: .ps 

R 

10 

any 

Other proGessing ... 


.ev 

<_ 


\”’ return to previous environment 

J 


It is also possible to initialize the parameters for an environment outside the . NP 
macro, but the version shown keeps aH the processing in one place and is thus 
easier to understand and change. 

Another major application for environments is for blocks of text that must be 
kept together. 

A number of the parameters diat control the text processing are gathered together 
into an environment, which can be switched by the user. The environment 
parameters are those associated with requests noting E in their Notes column; in 
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addition, partiaUy-coHected lines and words are in the environment. Everything 
else is global; examples are page-oriented parameters, diversion-oriented param¬ 
eters, number registers, and macro and string definitions. AH environments are 
initialized with default parameter values. 


Summary of the . Request 

Mnemonic: 

environment 

Form of R equest: 

.evN 

Initial Value: 

N=0 

If No Argument: 

Switch back to previous environment 

Explanation: 

Switch to environment N, where 0<A^. Switching is done in push-down 
fashion so that restoring a previous environment must be done with . ev 
rather than specific reference. 


o 


o 
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173 










trof f Request Summary 


This appendix is a quiek-reference summary of trof f and nrof f requests. In 
the following table, values separated by a : are for nrof f and trof f respec¬ 
tively. 

The notes in column four are explained at the end of this summary . 


Table A-1 Summary o/nrof f awrf trof f Requests 


Request 

Form 

Initial 

Value 

IfNo 

Argument 

Notes 

Explanation 

.ab text 

none 

User Abort 

— 

Displays text and terminates without 
further processing; flush output buffer. 

.ad G 

adjibodt 

adjust 

E 

Adjust output lines withi mode c &om 

• j- 

. af R e 

Arabic 

— 

— 

Assign:format to register/? (c = l,i, 
I.a,A)i 

.am XXyy 

— 

^yy-- 

— 

Append to a macro. 

.as XX string 

— 

ignored 

— 

Append string to string xx. 

.bd FN 

off 

— 

P 

Embolden font F hy N-% units .f 

\ .bd S FN 

off 


P 

Embolden Special Font when current 
fontisF.t 

.bp ±A^ 

N=:l 

— 

B1:,v 

Eject current page. Next page is 
number N. 

1 .br 

— 


B 

Break. 

.c2 G 


' 

E 

Set nobreak control character to c. 

.GC G 



E 

Set control character to c. 
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Table A-1 Summary of nro f l and trof f Requests — Continued 


Request 

Form 

Initial 

Value 

IfNo 

Argument 

Notes 

Explanation 

N 

off 

N=1 

B,E 

Center fcillowing N input text lines . 

\ .ch XX N 

— 

— 

V 

Change trap location. 

.Gs FNM 

off 

— 

P 

Constant character space (width) mode 
(fontF).t 

. cu N 

off 

N=l 

E 

Continuous underline in n ro f f; like 
.uliintroff. 

.da XX 

— 

end 

D 

Divert and append to jcc. 

.da XXyy 

— 

.yy=.. 

— 

Define or redefine macro xx; end at call 
of 30’- 

.di XX 

— 

end 

D 

Divert output to macro xx. 

.ds XX string 

— 

ignored 

— 

Define a string xx containing string. 

.dt N XX. 

— 

off 

D,v 

Set a diversion trap. 

. ec c 

\ 

\ 

— 

Set escape character. 

i .el anything 

— 

— 

— 

Else portion of if-else. 

.em XX 

none 

none 

— 

End macro is xx. 

.eo 

on 


— 

Turn off escape character mechanism. 

.ev N 

N=0 

previous 

— 

Environment switched down). 

\ .ex 

— 

— 

— 

Exit from nrof f/troff. 

. f G a b 

off 

off 

— 

Set field delimiter o and pad character 

b‘ 

\ .f i 

ifill 

— 

B,E 

Fill output lines. 

.f 1 

— 

— 

B 

Flush output buffer. 

i .fp NF 

R,I3,S 

ignored 

* 

Font named F mounted on physical 
position 1^<4. 
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Table A-l Summary of nrof f and troff Requests ^— Continued 


Request 

Form 

Initial 

Value 

If No 
Argument 

Notes 

E^)lanation 

.ft F 

Roman 

previous 

E 

Change to font F = a:, xc, or I through 

4. Also \£r, \f(xc, 

.fz SFN 

none 

— 

— 

Forces font F or S for special characters 
to be in size A. 

.he c 

\Wo 

\% 

E 

Hyphenation indicator character c. 

.hw wordl ... 

ignored 

— 

— 

Exception words. 

. hy N 

on 

previous 

E 

Hyphenate. N - mode. 

.ie cany thing 

— 

— 

—- 

If portion of if-else; all above forms 
(like . if). 

.if canythmg 

— 

— 

— 

If condition c true, accept anything as 
inputs for multirline MSQ\{anything \}. 

.if \canythmg 

— 

— 

— 

If condition! c false, accept anything. 

.if Nanything 

— 

— 

— 

If expression^/ > 0^ accept anything. 

: . if !anything 

— 

— 

— 

If expression // < 0, accept anything. 

. if 'stringl 'strmg2 ' anything 

— 

— 

— 

If stringl identicali to string2, accept 
anything. 

. if ! 'stringl 'string2 ' anything 

— 

— 


If stringl not identical! to stringl , 
accept anything. 

: • ig yy 

— 


— 

Ignore until call of yy . 

. in ±A^ 

N=0 

previous 

B,E,ni 

Indent. 

.it Nxx 

— 

off 

E 

Set an input^line count trap. 

\ .Ic c 

• 

none 

E 

Leader repetition character. 

.Ig N 

on 

on 

— 

Ligature mode on if A^> 0. 

.11 ±N 

6.5 in 

previous 

E,m 

Line lengths 

.Is N 

N=1 

previous 

E 

Output N -1 Vs after each text output 
line. 
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Table A-1 Summary QjTnrof f and troff Requests — Continued 


Request 

Form 

Initial 

Value 

IfNo 

Argument 

Notes 

Explanation 

.It ±N 

6.5 in 

previous 

Ejm 

Length df title. 

. me (C N 

— 

off 

Ejm 

Set margin character c and separation 

N. 

. mk R 

none 

internal 

D 

Mark current vertical place in register 

R. 

.na 

adjust 

— 

E 

No output line a<^usting. 

.ne AT 

— 

N=1V 

D,v 

Need N vertical space = vertical 
spacing). 

.nf 

m 

— 

B,E 

No filling or adjusting of output lines. 

.nh 

hyphenate 


E 

No hyphenation. 

■ nm ±NMSI 

off 

— 

E 

Number mode on or off, set parameters. 

.nn N 

— 

N=1 

E 

Do not number next iVilines. 

.nr R±NM 

— 

— 

u 

Define and set number register R by 
±A^; autOHincrement by M. 

.ns 

space 

— 

D 

Turn no-space mode on. 

. nx filename 

— 

end-oMle 

— 

Next file. 

\ .os 

— 

— 

— 

Output saved vertical distance. 

. pc c 

% 

off 

— 

Page number character. 

.pi program 

— 

— 

— 

Pipe output to(nrof f only). 

. pm / 

— 

dU 


Print macro names and sizes. If x 
present, print only total of sizes. 

.ps ±N 

lO-point 

previous 

E 

Point size, also \s±/V. f 

.pi ±N 

11 in 

11 in 

V 

Page length. 

.pn ±N 

N=1 

ignored 

— 

Next page number is N. 

.po ±N 

0: 26/27 in 

previous 

V 

Page offset. 
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Table A-1 Summary of nrof f and trof f Requests -— Continued 


Request 

Form 

Initial 

Value 

IfNo 

Argument 

Notes 

Explanation 

. rd prompt 

— 

prompt^BEL 

— 

Read insertiom 

.rn XX yy 

— 

ignored 

— 

Rename request, macro, or string xx to 
yy. 

.nti XX 

— 

ignored 

— 

Remove request, macro, or string. 

.rx R 

— 

— 

— 

Remove register R. 

.rs 

— 

— 

D 

Restore spacing. Turn no-space mode 
off. 

.rt ±N 

none 

intemali 

D,v 

Return (upward only) to marked verti^ 
cal place. 

. SO filename 

— 

— 

— 

Interpolate contents of source file name 
when . so encountered. 

. sp N 

— 

N^IV 

B,v 

Space vertical^ distance N in either 
direction. 

,ss N 

12/36 em 

ignored 

E 

Space-character size set to A//36 emit 

.svM 

— 

N=1V 

V 

S ave verticali distance N. 

.ta Nt ... 

0.8: O'Sim 

none 

E,m 

Tab settings: left type, unless t equals R 
(right)i or G (centered). 

.tc c 

space 

removed 

E 

Tab repetitioni character. 

.tL ±N 

— 

ignored 

B,E,ni 

Temporaiy indenti 

\ . 11 'left'center 'right' 

— 

— 


Three-part tide. 

.tm string 

— 

newline 

— 

Print string on terminal (to standard 
error). 

.tr abed.... 

none 

— 

O 

Translate a into bi, c into d, etc. on out- : 
puti 

\ .uf F 

Italic 

Italic 

— 

Underline font set to F (to be switched 
to by .ul)i 

'\ .ul N 

off 

A^=l 

E 

Underline input lines (italicize in 
troff). 
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Table A-1 Summary of nrof f and trof f Requests — Continued 


Request 

Form 

Initial 

Value 

IfNo 

Argument 

Notes 

E^lanation 

.VS N 

l/6in:12pts 

previous 

E.P 

Vertical base line spacing 

.wh Nxx 

— 

— 

V 

Set location trap. Negative is with 
respect to page bottom. 


t Point size changes have no effect in nrof f. 

I The use of' as the control character (instead of.) suppresses the break function. 


Table A-2 Notes in the Tables 


Note Explanation 


B Request normally causes a break. 

D Mode or relevant parameters associated with current diversion level. 

E Relevant parameters are a part of die current environment. 

O Must stay in effect until logical output. 

P Mode must be stiU or again in effect at the time of physical ouqtut. 

V Default scale indicator—if not specified, scale indicators are ignored. 

p Default scale indicator—if not specified, scale indicators are ignored. 

m Default scale indicator—if not specified, scMe indicators are ignored. 

u Default scale indicator—if not specified, scale indicators are ignored. 
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Font and Character Examples 


Font and Character Examples. 131 

B.l. Font Style Examples... Ig j 

B.2. Non-Ascn Characters and minus on the Standard Fonts. 182 

B.3. Non-ASCH Characters and G, +, and * on the Special 

Font. Ig 2 













Font and Character Examples 


B.l. Font Style Examples The following fonts are printed in 12-point, with a vertical spacing of 14-point, 

and with non-alphanumeric characters separated by 14-em space. They are Times 
Roman, Italic, Bold, and a special mathematical font. 


Times Roman 


abcdefghijklmnopqrstuvwxyz 

ABCDEFGHUKLMNOPQRSTUVWXYZ 

1234567890 

,/:; = ?[]! 

• □ — - _ 1/4 ‘/2 3/4 fi fl ff ffi ffl ° t' 0 ® © ™ 


Times Italic 


abcd^ghijklmnopqrstuvwxyz 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

1234567890 

• □ _ % ^2 Vffiflmffl ® © ™ 


Times Bold 


abcdefghijklmnopqrstuvwxyz 

ABCDEFGHUKLMNOPQRSTUVWXYZ 

1234567890 

!$%&()‘’*4.-.,/:; = ?[]! 

• □ — - _ 1/4 V 2 3/4 fi fl ff ffi ffl ° t' 0 ® © ™ 


Special Mathematical Font 

" 'V_'“/<>{ }##+- = * 

a P y 5 e C Tj 01K p V ^ 0 7c p a q X 0) ([) X xjT CO 

rA0ASnSYO'PQ 

4 ix-4-±unc3C3oo3 

§v-,j«06t=>.^iofOJ{HUn f 
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B.2. Non-ASCn Characters 
and minus on the 
Standard Fonts 

Char 

> 

Input 

Name 

/ 


i 

\ i(em 


- 

\ (hy 


- 

\- 


• 

\ (bu 


□ 

\ (sq 


_ 

\(ru 


1/4 

\(14 


% 

\ (12 



\ (34 


Character 


Input 

Character 

Name 

Char 

Name 

Name 

close quote 

fl 

\(fi 

fi 

open quote 

fl 

\(fl 

fl 

3/4 Em dash 

ff 

\(ff 

ff 

hyphen or 

ffi 

\ (Fi 

ffi 

hyphen 

ffl 

\(F1 

ffl 

current font minus 

0 

\(de 

degree 

bullet 

t 

\ (dg 

dagger 

square 

/ 

\(fm 

foot mark 

rule 

0 

\ (ct 

cent sign 

1/4 

® 

\ (rg 

registered 

1/2 

© 

\ (co 

copyright 

3/4 





B.3. Non-ASCn Characters The ASCII characters (2), <, >,\ {,^ and _ exist on/j on the special 

and =, and font and are printed as a l^em space if that font is not mounted. The following 

* on the S pedal Font characters exist only on the special font except for the upper case Greek letter 

names followed by t which are mapped into upper case English letters in what¬ 
ever font is mounted on font position one (default Times Roman). The special 
math plus, minus, and equals are provided to insulate the appearance of equations 
from the choice of standard fonts. 


Table B-1 Summary of txoff Special Characters 


Char 

Input 

Name 

Character 

Name 

Char 

Input 

Name 

Character 

Name 


\(pl 

math plus 

a 

\ (*s 

sigma 

- 

\ (mi 

math minus 

<; 

\ (ts 

terminal sigma 

= 

\ (eq 

math equals 

x 

\(*t 

tau 

* 

\(** 

math star 

\> 

\(*u 

upsilon 

§ 

\ (se 

section 


\(*f 

phi 


\ (aa 

acute accent 

X 

\i(*x 

chi 


\ (ga 

grave accent 

y 

\ ( *q 

psi 


\ (ul 

underrule 

GO 

\ (*w 

omega 

7 

\ (si 

slash (matching backslash) 

A 

\(*A 

Alphat 

a 

\(*a 

alpha 

B 

\ ( *B 

Betat 

P 

\ ( *b 

beta 

r 

\ (*G 

Gamma 

Y 

\ (*g 

gamma 

A 

\(*D 

Delta 

5 

\ (*d 

delta 

E 

\ ( *E 

Epsilont 

e 

\ ( *e 

epsilon 

z 

\ (*z 

Zetat 

1 

\ (*z 

zeta 

H 

\ (*Y 

Etaf 

n 

\ (*y 

eta 

© 

\ (*H 

Theta 

e 

\ (*h 

theta 

I 

\(*I 

lotat 

1 

\(*i 

iota 

K 

\ ( *K 

Kappat 


Asun 
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Table B-1 Summary of t rof f Special Characters— Continued 



Input 

Character 


Input 

Character 

Char 

Name 

Name 

Char 

Name 

Name 

K 

\ (*k 

kappa 

A 

\ (*L 

Lambda 

X 

\ (*1 

lambda 

M 

\ ( *M 

Mut 

M- 

\ ( *m 

mu 

N 

\ (*N 

Nut 

V 

\ (*n 

nu 

S 

\ (*C 

Xi 

% 

\(*c 

xi 

0 

\ (*0 

Omicront 

0 

\ (*o 

omicron 

n 

\ (*P 

Pi 

7C 

\ (*P 

pi 

p 

\ ( *R 

Rhot 

P 

\ C*r 

rho 

z 

\ (*s 

Sigma 

T 

\ (*T 

Taut 

oo 

\ (if 

infinity 

Y 

\ (*U 

Upsilon 

a 

\ (pd 

partial derivative 

O 

\ (*F 

Phi 

V 

\ (gr 

gradient 

X 

\ (*x 

Chit 

—1 

\ (no 

not 


\(*Q 

Psi 

J 

\ ( is 

integral sign 

a 

1 

\ (*W 

Omega 

oc 

\(pt 

proportional to 

V 

\{sr 

square root 

0 

\ (es 

empty set 


\ (rn 

root en extender 

e 

\ ( mo 

member of 

> 

\ (>= 

>= 

1 

\(br 

box vertical mle 

< 

\«= 

<= 

$ 

\ (dd 

double dagger 


\(== 

identically equal 


\ (rh 

right hand 


\{~= 

approx = 

<= 

Vdh 

left hand 


\ (ap 

approximates 

1 

\ (or 

or 


\(! = 

not equal 

O 

\ (ci 

circle 


\(-> 

right arrow 

r 

\ (It 

left top of big curly 
bracket 


\ «- 

left arrow 

i 

\ (lb 

left bottom 

t 

\ (ua 

up arrow 

1 

\ (rt 

right top 

\ ( da 

down arrow 

j 

\(rb 

right bot 

X 

\ (mu 

multiply 


\ (Ik 

left center of big 
curly bracket 


\ (di 

divide 


\'(rk 

right center of big 
curly bracket 

± 

\(+- 

plus-minus 

I 

\ (bv 

bold vertical 

U 

\ (cu 

cup (union) 

L 

\(lf 

left floor (left bottom 
of big square bracket) 

n 

\ (ca 

cap (intersection) 

J 

\ (rf 

right floor (right 
bottom) 

d 

\ (sb 

subset of 

r 

\(lc 

left ceiling (left top) 

3 

\ (sp 

superset of 

1 

\ (rc 

right ceiling (ri^t top) 

3 

\ (ib 
\ ( ip 

improper subset 
improper superset 

\ 

\e 

backslash (escape character' 
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Escape Sequences 
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Escape Sequences 


Note: The escape sequences \\, \ ., \", \$, \*, \a, \n, \t, and \(newlme) 
are interpreted in copy mode (see Chapter 10), 


Table C-1 trof f Escape Sequences 


Escape 

Sequence 

Meaning 


\ (to prevent or delay the interpretation of\) 

\e 

Printable version of the current escape character. 

\' 

(acute accent); equivalent to \ ( aa 

\: 

(grave accent); equivalent to \ (ga 


- Minus sign in the current font 

\ . 

Period (dot) (see . de) 

\ (space) 

Unpaddable space-size space character 

\ 0 

Digit-width space 

\ 1 

1/6 em-narrow space character (zero width in nrof f) 


1/12-em half-narrow space character (zero width in 
nroff) 

\& 

Non-printing, zero width character 

\! 

Transparent line indicator 

\" 

Beginning of comment 

\$N 

Interpolate argument 1<N<9 

\% 

Def^t optional hyphenation character 

\ (xc 

Character named xx 

\*x, \* (xc 

Interpolate string x or xc 

\a 

Non-interpreted leader character 

\b ' abc...' 

Bracket building function 


Interrupt text processing 

\d 

Forward (^own) 1/2-em vertical motion (1/2-line in 
nxof f) 

\fx, \f (xc, \£N 

Change to font named x or xc, or position N 
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Table C-1 t r o f f Escape Sequences — Continued 


Escape 

Sequence 

Meaning 

\h’N' 

Local horizoEital motion; move right N (negative=left) 

X^ix 

Mark horizontal input place in register jc 

\1' Me ’ 

Horizontal line drawing function (default character is 
baseline rule in t rof f or underline in nrof £; option¬ 
ally with character c ) 

\L'Mc’ 

Vertical line drawing function (default character is box 
rule; optionally with character c ) 

\njc, \n (X3C 

Interpolate number register xorxx 

Xo'abc...’ 

Overstrike characters a, b, c,... 


Break and spread output line 

\r 

Reverse one-em vertical motion (reverse line in nr of f) 

\sN, \s±N 

Point-size change function 

\t 

Non-interpreted horizontal tab 

\u 

Reverse (up) 1/2-em vertical motion (1/2-line in nrof f) 

\v'M’ 

Local vertical motion; move down N (negative=up) 

\vi'string' 

Interpolate width of string 

\x'N' 

Extra line-space function (negative before, positive 
after) 

\ zc 

Print c with zero width (without spacing) 

\ \{ 

Begin conditional input 

: \} 

End conditional input 

\(newline) 

Concealed (ignored) newline 

: 

X, any character not listed above 
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191 


o 







Table D-1 


Table D-2 


D 

Predefined Number Registers 


General Number Registers 


Register 

Name 

Description 

c . 

Input line-number in current input file; same as . c. 

: % 

Current page number. 

ct 

Character type (set by width function). 

dl 

Width (maximum) of last completed diversion. 

dn 

Height (vertical size) of last completed diversion. 

dw 

Current day of the week (1-7). 

dy 

Current day of the month (1-31). 

hp 

Current horizontal place on input line. 

In 

Output line number. 

mo 

Current month (1-12). 

nl 

vertical position of last printed text baseline. 

1 sb 

Depth of string below base line (generated by width function); 

■ St 

Height of string above base line (generated by width function). 

yr 

Last two digits of current year. 


Read-Only Number Registers 


Register _ . . 

° Description 


. $ Number of arguments available at the eurrent maero level. 

. A Set to 1 in trof f , if-a option used; always 1 in nrof f. 

. H Available horizontal resolution in basie units. 

. L Current line-spaeing parameter (.Is). 

. P 1 if current page is printed, odierwise zero. 

. T Set to 1 in nrof f , if -T option used; always 0 in trof f . 

. V Available vertical resolution in basie units. 

. a Post-line extra line-space most recently utilized using \ x' A ’. 
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O 

Table D-2 Read-Only Number Registers — Continued 


Register 

Name 

Description 

. c 

Number of lines read from current input file. 

.d 

Current vertical place in current diversion; equal to nl, if no 
diversion. 

.f 

Current font as physical quadrant (1-4). 

.h 

Text baseline high-water made on current page or diversion. 

. i 

Current indent. 


Current adjustment mode and type. 

^ .k 

Horizontal text portion size of current output line. 

; .1 

Current line length. 

1 .n 

Length of text portion on previous output line. 

. o 

Current page offset. 

.p 

Current page length. 

• s 

Current point size. 

• t 

Distance to the next trap. 

• ^ 

Equal to 1 in fill mode and 0 in nofiU mode. 

\ • ^ 

Current vertical line spacing. 

. w 

Width of previous character. 

.X 

Reserved version-dependent register. 


Reserved version-dependent register. 

1 . z 

Name of current diversion (a string, not a numbei). 
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trof f Output Codes... 195 

E. 1. Codes O Oxxxxxx — Flash Codes to Expose Characters. 196 

E.2. Codes Ixxxxxxx — Escape Codes Specifying Horizontal 

Motion. 197 

E.3. Codes 01 Ixxxxx — Lead Codes Specifying Vertical Motion. 197 

E.4. Codes 01 O lxxxx — Size Change Codes. 197 

E.5. Codes 010 Oxxxx — Control Codes... 198 

E.6. How Fonts are Selected. 199 

E.7. Initial State of the C/A/T. 199 
























t r o f f Output Codes 


As we mentioned before, t rof f is geared up to produce binary codes for a pho¬ 
totypesetter caEed a C/A/T. This appendix describes the codes for the C/A/T in 
detail. This information is for people who want to translate C/A/T codes for 
other purposes. 


The basic mechanism of the C/A/T typesetter is a revolving drum divided into 
four quadrants. On each quadrant of &e drum you can mount a strip of film — 
one strip of film corresponds to a font. Each font has 108 characters in it. Char¬ 
acters are exposed on the final photographic paper by ‘flashing’ a light through 
the appropriate position of the film strip on the dmm. The actual font to be used 
is selected (as you will see later) by a combination of ‘rail’, ’mag’, and ‘font- 
half — the terms ‘rail’ and ‘mag’ are hangovers from very old hot-lead typeset¬ 
ting technology and have no place in electro-mechanical systems, but they were 
carried over because typesetters can’t handle new things. Point size changes are 
handled in the C/A/T by a series of magnifying lenses. 

The C/A/T’s basic unit of length (machine imit) is 1/432 inch (there are six of 
these units to a typesetter’s ‘point’). The quanhun of horizontal motion is one 
unit. The quantum of vertical motion is three units (1/144 inch or half a point), 
tro f f uses the same system of units in its internal computations. 

The C/A/T phototypesetter is driven by sending it a sequence of one-byte (eight- 
bit byte) codes to specify characters, fonts, point sizes, and other information. 
The encoding scheme used was obviously desired by someone wanting to send 
the minimum amount of information across a communications channel at the 
expense of doing vast amounts of work in the computer driving the typesetter. 

A complete C/A/T file is supposed to start with an initialize code (described 
later), followed by an escape-16 code, then the body of the text destined for the 
C/A/T. The whole file ends with 14 inches of trailer, followed by a stop code. In 
practice, looking at t ro f f’s output file has generated disagreements on what the 
file really looks like, but we don’t have a C/A/T aroxmd to reaEy try it out. 

Bit 7 of a code byte classifies the byte into one of two major types: 


BIT 


7 6 5 4 3 2 1 0 


Major Code 
Type 


Further Encoding 
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The top bit (bit 7) is encoded thus; 

1 — An Escape Code, specifying horizontal motion, as described below. 


BIT 


7 6 5 4 3 2 1 0 


Bit7 = l 
Escape Code 


One’s Complement of Amount of Motion 


0 — indicates that bits 7 and 6 are used to further encode the code byte, as fol¬ 
lows: 


BIT 


7 6 5 4 3 2 1 0 


Flash Code or 
Gontrdl Code 


Further Encoding 


The two upper bits have these meanings: 

00 — A Flash Code, which selects a character out of a font, as described below. 


BIT 


7 6 5 4 3 2 1 0 


Bits 6 and 7 = 00 
Flash Code 


Character Nurriber to Flash 


01 — A Control Code, which is then further encoded into one of two categories 
depending on whether the next hit is a one or a zero: 


BIT 


7 6 5 4 3 2 1 0 


Control Code 


Further Encoding 


1 — This is a lead code , described below, or 

0 — in which case the control code is further encoded into one of three 
categories of: 

□ Initialization and termination. 

□ Selecting fonts. 

□ Specifying the direction of motion for escapes and leading. 

We have finally reached the end of this encoding scheme. The following sections 
discuss each type of code in detail. 


E.l. 


Codes 0 Oxxxxxx — 

Flash Codes to Expose 
Characters 


A code with the bits six and seven equal to zero (0 Oxxxxxx) is a flash code . A 
flash code specifies flashing one of 63 characters — the lo wer six bits of the flash 
code specify which character to flash. This is not enough character combinations 
to select even all the characters within a single font (there are 108 characters per 
font) and so there are control codes (described later) to select the font and which 
half of the font. Given that a specific font is selected via the rail, mag, and (for 
the eight-font C/A/T) the ri/t codes, you then select an upper-font-half or a 
lower-font-half. The lo wer-font-half is the first 63 Characters of the font, and the 
upper-font-half is the remaining 45 characters of the font. A flash code of greater 
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E.2. Codes Ixxxxxxx — 
Escape Codes 
Specifying Horizontal 
Motion 


than 46 in the upper-half of the font is considered illegal. 

A code with bit seven equal to 1 (Ixxxxxxx) is an escape code. An escape code 
specifies horizontal motion. The C/A/T is a boustrophedonie device — that is, it 
can move in both directions, and so die direction of motion is specified by one of 
the control codes described later on. The amount of horizontal motion is 
specified by the one ’ s complement of the lower seven bits of the escape code. 


E.3. Codes 01 Ixcccx — 
Lead Codes Specifying 
Vertical Motion 


A codes with the top three bits equal to 011 is a lead code . A lead code is a 
subset of the confi-ol codes in that the top three bits are Oil. Such a code 
specifies vertical motion. The amount of the vertical motion is specified by the 
one’s complement of the lower five bits, in vertical quanta. ‘Lead’ is a 
typesetter’s term deriving from the days of hot-lead machines — the terminology 
sticks with us because the industry moves slowly. 


E.4. Codes 010 Ixxxx — A byte with the top four bits equal to 0101 is a size-change code. Such a code 

Size Change Codes specifies movement of a lens mrret and a doubler lens to change the point size of 

the characters. The size-change codes are as follows: 


Table E-1 Size Change Codes 


Point-Size 

Binary Code 

Octal Code 

Point-Size 

Binary Code 

Octal Code 

' 6 

01011000 

0130 

16 

01011001 

0131 

I 1 

01010000 

0120 

18 

01010110 

0126 

1 8: 

01010001 

0121 

20 

01011010 

0132 

i 9 

01010111 

0127 

22 

01011011 

0133 

10 

01010010 

0122 

24 

01011100 

0134 

11 

01010011 

0123 

28 

01011101 

0135 

12 

01010100 

0124 

36 

01011110 

0136 

14 

01010101 

0125 





Changes in size using the doubler lens change the horizontal position on the 
page: 


If you changefrom: 

Follow the change with: 

Single to double 

A forward escape of 55 quanta 

Double to single 

A reverse escape of 55 quanta i 
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Table E-2 Single Point-Sizes versus Double Point-Sizes 


Single 

Double 

6 

16 

7 

20 

8 

22 

9 

24 

10 

28 1 

11 

36 1 

12 


14 


18 



E.5. Codes OlOOiOXt— Abyte with the top four bits equal to OIGO is ^ control code. Not all of the con- 

Control Codes trol codes have meaning to the typesetter. The control codes are in three classes, 

namely: 

□ Initialization and termination. 

□ Selecting fonts. 

□ Specifying the direction of motion for escapes and leading. The control 
codes and their meanings are: 


Table E-3 CIA/T Control Codes and their Meanings 


Category 

Meaning 

Binary Code 

O ctal Co de 

Initializing 

Initialize 

01000000 

0100 

and Terminating 

Stop 

01001001 

0111 


Upper Rail 

01000010 

0102 


Lower Rail 

01000001 

0101 


Upper Mag 

01000011 

0103 

Selecting Fonts 

Lower Mag 

Tilt Up 

01000100 
01001110 

0104 

0116 


TMt Down 

01001111 

0117 


Upper Font Half 

01000110 

0106 


Lower Font Half 

01000101 

0105 

Specifying Direction 

Escape Forward 

01000111 

0107 


Escape Backward 

0100 1000 

0110 

Of Motion 

Lead Forward 

01001010 

0112 


Lead Backward 

01001100 

0114 
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Note tiiat tilt up and dlt down are unimplemented op-eodes oa. the four-font 
C/A/r. However, the illustrious hackers at Berkeley implemented a program 
called r vcat to drive the Versatec or the Varian printers, and they used the 
0116 g code to mean ‘multiply the next lead-code by 64 ’ to avoid having enor¬ 
mous runs of small lead-codes. 


E.6. How Fonts are Fonts are selected by a combination of rail, mag, and tilt. The tilt codes exist 

Selected only on the eight-font C/A/T and this is the only difference between the two 

machines that is visible to the user. The standard version of trof f doesn’t 
know about the eight-font machine — University of Illinois is one of the places 
that hacked over trof f to make it understand the eight-font C/A/T. The 
correspondence between rail, mag, and dlt codes is shown in this table: 

Table E-4 Correspondence Between Rail, Mag, Tilt, and Font Number 


Rail 

Mag 

Tilt 

Four-Font 

Eight-Font 

Lower 

Lower 

Up 

1 

1 

Lower 

Lower 

Down 

1 

2 

Upper 

Lower 

Up 

2 

3 

Upper 

Lower 

Down 

2 

4 

Lower 

Upper 

Up 

3 

5. 

Lower 

Upper 

Down 

3 

6 

1 Upper 

Upper 

Up 

4 

7 

^ Upper 

Upper 

Down 

4 

8 


E.7. Initial State of the For those wishing to write postprocessors to hack over C/A/T codes, here is the 

C/A/T initial state of the beast: 


Attribute 

Imtial State 

Escape 

Forward 

Lead 

Forward 

Font-Half 

Lower 

Rail 

Lower 

Mag 

Lower 

Tilt 

Down 


Asun 
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Index 


Special Characters 

. $ (number of arguments) number register, 109 
\& (zeio-widtb nonhprinting);func 137 
% (page-number);number register, 42, 121 
\ (unpacidable space) functioni 136 
\ " (diin space) function^ 136 
\ I (thick space) functioui 136 

0 

\0 (digit^-size space) function^ 134 

A 

\a (leader character) function* 72 
. a (post^line extra space) number register, 52 
. ab (abort) request^ 166 
access format for number registers, 125 
accessing strings, 98 
. ad (adjust) request^ 21 
adjusting, 17 
center, 21 

fliishdeft; ragged right; 21 
flush right; ragged left^ 21 
justified, 21 

. af (format of number register) request, 125 
. am (append to a macro) request; 112 
append to a 

diversion^ 114 
macro, 112 
string, 99 

arguments to macros, 109 
arithmetic expressions withi number registers, 124 
.as (append to string) request; 99 
auto-incrementing number registers, 123 
automatic hyphenation; 24 

B 

\b (bracket) function; 142 

backslash - how to print it ini trof f, 9 

basic request, 8 

. bd (boldface) request; 60 

beginpage, 41 

blank lines, 19 

bold-face request; 60 

box lines, 145 

. bp (start new page) request; 41 


. br (break lines) request; 20,19 
bracket drawing function; 142 
break request; 19,20 

c 

\c (continuation lirie); function; 20 
C/A/T codes 
control; 196 
escape, 196 
file organization; 195 
flash; 196,196 

. g 2 (set no-break control character) request; 150 
. Gc (set control character) request, 150 
. Ge (center lines) request, 28, 27 28! 

centered tabs, 68 

. Gh (change position of a trap) request; 116 
change bars, 145 
change position! of a trap, 116 
character translation (substitution), 150 
comments in t rof f source files, 9 
concealed newlines, 10 
conditionalipage break, 42 
conditionali processing of input, 157 
conditional request 
.el, 159 
.ie,159 
.if, 157 
. ig, 160 

constant character space widthi mode request; 54 

continuation lines, 10, 20 

continuously underline request, 29 

control character setting; 150 

control code, 196 

control lines in t r o f f, 8 

copy mode, 112 

creating number registers, 121 

. Gs (set constant character space width mode) request, 54 
Gt (character type) number register, 141 
. Gu (continuously underline) request, 29 

D 

\ d (move down) function; 131 

. d (vertical place in current diversion) number register, 114 
. da (append to a diversion) request; 114 
. de (define macro) request; 105 
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defining troff objects 
macros, 105 
number registers, 121 
strings, 98 

deleting number registers, 127 
device resolution, 10 
. di (divert text) request, 114 
diversion traps, 114,116 
diversions, 113,114 
divert text, 114 

dl (width of last finished diversion) number register, 113 
dn (height of last finished diversion) number register, 113 
document preparation 
formatters, 3 r/irw 13 
nrof f program, 3r/irM 13 
text formatters, 3 r/irw 13 
troff program, 3 thru 13 
drawing in trof f 
boxes, 145 ^ 

brackets, 142 
horizontal lines, 143 
vertical lines, 143,144 
. ds (define string) request, 98 
. dt (set a diversion trap) request, 116 
dy (day of month) number register, 121 

E 

. ec (set escape character) request, 149 

.el (elseconditional)request, 159 

. em (set the end^of-processing trap) request, 117 

end-ofnfile, 19 

end^of-processing traps, 117 

end-of-sentence, 18 

environment switching, 169 

.eo (set escape of^ request, 149 

escape character, 149 

escape code for C/A/T, 196 

. ev (switch environment) request, 169 

. ex (terminal message^ request, 94 

expressions with number registers, 124 

F 

. f (current font) number register, 62 

. fc (set field characters) request, 74 

. f i (fill) request, 23 

field character, 74 

fields, 74 

fill request, 23 

filler Character, 18 

filling, 17 

. fl (flush buffer) request, 166 

flash code, 196,196 

flush output buffer, 166 

font position request, 59 

footers, 81, 85 

force font size request, 59 

. fp (change font position) request, 59 

. ft (set font) request, 58 

. f z (force font size) request, 59 


G 

general number registers 

% —page-number, 42, 121 
c t —character type, 141 
dl —width of last finished diversion, 113 
dn —height dflast finished diversion, 113 
dy — day of month, 121 
mo —month of year, 121 
nl —vertical position of last baseline, 121, 113 
sb — string depth below baseline, 140 
St —string height above bascHne, 140 
y r — last two digits of year, 121 
get vertical space request, 47 

H 

\h (horizontal motioi^ function, 133 
. h (text high*^ water marie) number register, 18, 114 
half em-space, 136 
half4ine motions 

\d (move down) function, 131 
\u (move up) function, 131 
hanging indent, 39 
hard blank, 17 

. he (hyphenation character) request, 26 
headers, 81, 85 
horizontal lines, 143 
horizontal motion, 133,134,136,138 
horizontal place marker, 141 
. hw (hyphenate word) request, 25 
. hy (hyphenate) request, 24, 25 
hyphenation, 24 
automatic, 24 
control, 24 
indicator, 25 
indicator Character, 26 
special cases, 25 
specifying location, 25 
turn on and off, 24 

I 

. i (current indent) number register, 38, 40 
. ie (ifielse conditional) request, 159 
. if (conditional processing) request, 157 
. ig (ignore lines) request, 160 
ignoring input lines, 160 
. in (indent) request, 37 
iti^line functions 

\ (unpaddable space) function, 136 
\ & (zero-width non-printing) function, 137 
\ " (thin space) function, 136 
\ I (thick space) function, 136 
\0 (digit-size space) function, 134 
\ a (leader character) function, 72 
\b ^racket) function, 142 
\ c (continuation line) function, 20 
\d(move down) function, 131 
\h (horizontal motion) function, 133 
\k (mark horizontal position) function, 141 
\1 (horizontal line) function, 143 
\L (vertical line) function, 144, 143 
\o (overstrike^ function, 138 
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in-line funcdom, continued 

\p (break and spread) function^ 19 
\r (reverse line) Junction^ 143 
\u (move up) function^ 131 
\ V (vertical motion) function^ 132 
\w (width) function 140 
\x (get extra line space) function; 52 
\z (zero motion) function; 139 
include 

from file, 89 
from standard input; 92 
incrementing number registers, 123 
indentation 

first line of paragraph; 38 
permanent; 37 
temporary, 38 

input^-line-count traps, 114; 116 
interpolating mrniber registers, 121, 125 
interrupted line, 20 

. it (set an mput^line-count trap) request, 116 
italic correction; 136 
itemized lists, 39 

J 

. j (current adjustment indicator) number register, 21 




K 

\k (mark horizontal position) function^ 141 

L 

\1 (horizontal line) function, 143 
\L (vertical line) function; 144,143 
. 1 (line-length) number register, 36 
large boxes, 145 

. 1g (set leader character) request, 73 
leaders and leader characters, 71,72 
Mt margin, 35 
length of title, 83 

. Ig (set ligature mode) request, 63 
ligatures, 63 

line adjustment indicators 
both, 21 
center, 21 
indentation; 37 
left, 21 
normal; 21 
right; 21 
line drawing 

functions, 143,144 
horizontal, 143 
vertical; 143, 144 
line numbering 
start, 153 
suspend, 154 
line spacing request, 51 
line-length, 35 

.11 (set line-length) request; 35 
local motions, 132 

\ (unpaddable space) function, 136 
\& (zero-width non^printing) function; 137 


local motions, continued 

\ (thin space) function; 136 
\ I; (thick space) function; 136 
\0 (digit^size space) function; 134 
\b ^racket) fimction* 142 
\d (move down) function, 131 
\h horizontal motion) function; 133 
\1 (horizontal line) function; 143 
\L (vertical line) function, 144,143 
\ o (overstrike) ftmction, 138 
\r (reverse line) function, 143 
\u (move up) function, 131 
\ V (vertical motion) function, 132 
\ z (zero motion) function, 139 
long lines, 10 

. Is (change line spacing) request; 51 
. It ^et length of title) request, 83 

M 

macros, 9, 105 

append to* 112 
arguments to* 109 
copy mode, 112 
defining, 105 
embedded blanks. 111 
invoking; 105 
print names and sizes, 165 
remove, 107 
renaming; 108 
margin character, 145 
margins on a page 

with nroff and troff, 21,35 
mark 

horizontal position, 141 
vertical position; 43, 114 
.me (margincharacter)request, 145 
measure, 35 

.mk (mark vertical position) request, 43, 114 
mo (month of year) number register, 121 

N 

. n (text length) number register, 18 

. na (no adjust) request, 22 

. ne (need space) request, 42 

need space, 42 

new page, 41 

.nf (no fill)^ request; 23 

. nh (no hyphenation) request; 25, 24 

n l (vertical position of last baseline) number register, 121,113 
. nm (number lines) request; 153 
. nn (ho number) request, 154 
no adjust request, 22 
no fill request, 23 
no hyphenation request, 24,25 
no space mode request; 53 
no-break control character setting, 150 
non-printing character, 137 
. nr (set number register) request; 121 
nrof f command 
exit from, 94 
introduction to, 3,13 
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, n s (no space mode) request, 53 
nunlber registers, 121 
access format, 125 
auto^incrementing, 123 
creating, 121 
expressions, 124 
interpolating, 121 
removing, 127 
setting, 121 

numbering lines, 153,154 
. nx (next file) request, 91 

o 

\o (overstrike) function, 138 
. o (page-offset) number register, 35 
one^twelfth em-§pace, 136 
orphans, 43 

. os (output saved verticd space) request, 53 
output saved vertical request, 53 
overstriking, 138 

P 

\p (break and spread) function, 19 

• P (page-length) nuinber register, 41 

padding indicators, 74 

page length changes, 41 

page number, 42, 84 

page traps, 114 

page^offset, 35 

. pc (set page number Character) request, 84 
. p i (pipe to program) request, 91 
pipe to program, 91 
. pi (set page length) request, 41 
. pm (print macros) request, 165 
. pn (set page number) request, 42 
. po (set page-offset) request, 35 
point size request, 49 
predefined number registers 
% —page-number, 42,121 
. $ — number of arguments, 109 
. a — post^line extra space, 52 
. d — verticd place in current diversion, 114 
. f — current font, 62 
. h — text high-^water marie, 18,114 
. i — current indent, 38,40 
. j —current adjustment indicator, 21 
. 1 — line^length, 36 
. n — text length, 18 
. o —page-offset, 35 
. p — pagedength, 41 
. s —point-size, 49 
. t — distance to next trap, 113,115 
. u — fill mode indicator, 23 
. V — vertical spacing, 51 
. z —name of current diversion, 114 
ct — character type, 141 
dl — width of last finisihed diversion, 113 
dn — height of last finished diversion, 113 
dy — day of month, 121 
mo —month of year, 121 
nl —vertical position of last baseline, 121,113 


predefined number registers, 

sb — string depth below baseline, 140 
st —string height above baseline, 140 
yr —last two digits Of year, 121 
print macros, 165 
Procrustean mold, 23 
. ps (change point size) request, 49 

R 

\ r (reverse line) function, 143 
. rd (read standard input) request, 92 
read-only number registers 

. $ ^ number of arguments, 109 
. a —postdine extra space, 52 
. d — vertical place in current diversion, 114 
. f —current font, 62 
. h — text high-^water marie, 18,114 
. i —current indent, 38, 40 
. j —current adjustment indicator, 21 
. 1 —linedength, 36 
. n — text length, 18 
. o —page^offset, 35 
. p — page^length, 41 
. s —point-size, 49 
. t —distance to next trap, 113,115 
. u —fill mode indicator, 23 
. V — vertical spacing, 51 
. z —name of current diversion, 114 
reading from standard input, 92 
referencing strings, 98 
removing 

macro definitions, 107 
number registers, 127 
string definitions, 107 
renandng macros and strings, 108 
requests, 8 

. ab —hbort, 166 
. ad — adjust, 21 

. a f — format of number register, 125 
.am — append to a macro, 112 
. as — appendlo string, 99 
. bd — bre^ line, 60 
. bp — begin page, 41 
. br — break line, 20,19 
. c2 — set no-break control Character, 150 
. cc — set control character, 150 
. ce — center lines, 28, 21 thru 28 
. ch —change position Of a trap, 116 
. cs —constant spacing, 54 
-cu — continuously underline, 29 
. da — append to a diversion, 114 
. de — define macro, 105 
. di —divert text, 114 
. ds — define string, 98 
. dt — set a diversion trap, 116 
. e c — set escape character, 149 
. el —else conditional, 159 
. em — set the end-Of-processing trap, 117 
. eo — set escape off, 149 
. ev — switch environment, 169 
. ex —exit from nroff or trof f, 94 
. f c — set field characters, 74 
. f i — fill, 23 


-204- 



Index — Continued 





requests, continued 

. fl —flush buffer, 166 
. f p — font position^ 59 
. ft — setfontvSS 
. f z —force font size, 59 
. he —hyphenation character, 26 
. hw — hyphenate wordi 25 
. hy —- hyphenate, 24, 25 
. ie — if-else conditional; 159 
.if — conditional processing, 157 
. ig — ignore lines, 160 
. in — indent; 37 

. it — set an inputkline-count trap, 116 

. Ic — set leader character, 73 

. Ig — set ligature mode, 63 

.11 — set line-length; 35 

. Is —line spacing, 51 

. It — set lengthi of title, 83 

. me — margini character, 145 

. mk — mark vertical position; 43* 114 

. na — no adjust; 22 

. ne — need space, 42 

.nf —no fill; 23 

. nh — no hyphenation; 25* 24 

. nm—number lines* 153 

. nn — no numbering; 154 

. n r — set number register* 121 

. ns —no space mode* 53 

. nx — read next source file, 91 

. os—output saved vertical! space, 53 

. pc — set page number character, 84 

. pi •— pipe to program; 91 

. pi —set page length, 41 

. pm — print macros, 165 

. pn — set page number, 42 

. po — set page-offset; 35 

. p s — point size, 49 

. rd — read from: standard! input; 92 

removing, 107 

renaming; 108 

. rm — remove request; macro, or string, 107 
. rn — rename request, macro, or string, 108 
. rr — remove number register, 127 
. rs —restore space mode, 53 
. rt —return to position; 44, 114 
. so — switch source file, 89 
. sp—space, 47 
. s s — set space size, 54 
. sV — save vertical space, 52 
. ta — set tab stops, 67 
. t G — set tab character, 69 
. ti — temporary indent, 38 
. tl — define title, 85 
. tm — terminal message, 94 
. t r — translate characters, 150 
. uf — underline font; 29 
. ul — underline, 28 
. vs — vertical! spacing, 51 
. wh — 'wh&u somethings 115, 82 
resolution j 10 

restore space mode request; 53 
return to marked vertical! position; 114: 
return to vertical position^ 44 


reverse line fiinction; 143 
revision bars* 145 
right^adjusted tabs, 68 

. rm (remove request; macro, or string) request, 107 
. rn (rename request; macro, or string) request; 108 
. rr (remove number register) request; 127 
. rs (restore space mode) request; 53 
.rt (return to position) request; 44, 114 
rules 

horizontal; 143 
vertical; 143, 144: 
running headers and footers, 81, 85 

s 

. s d^int^size) number register, 49 
save vertical: space request; 52 
saving state, 169 

sb (string depth below baseline) number register, 140 

sentence endings, 18 

set font request; 58 

set ligature mode request, 63 

set page number, 42 

set space-character size request; 54 

setting line-length; 35 

setting number registers, 121 

setting tabs, 67 

skipping input lines, 160 

.so (switch source) request, 89 

. sp (jget vertical space) request, 47 

space request; 47 

spaces, 19 

. ss (set space-character size) request, 54 

St (string height above baseline) number register, 140 

standard input 

reading troff input from; 92 
start line numbering, 153 
start new page, 41 
strings, 97 

accessing; 98 
appending to, 99 
beginning with blanks, 98 
defining; 98 
removing, 107 
renaming; 108 
substituting characters, 150 
suspend line numbering; 154 
. s V (save vertical space) request, 52 
switch source file, 89 

T 

. t (distance to next trap) number register, 113,115 

. ta (set tab stops) request; 67 

tabs 

absolute, 68 
centered, 68 
relative, 68 

replacement character, 69 
right^adjusted; 68 
setting, 67 
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. t c (set tab character) request, 69 
temporary indent of one line, 38 
text lines 

as trof f input, 8 
ignoring, 160 
words in, 17 
thick space, 136 
thin space, 136 
three-part titles, 85 
. t i (temporary indent) request, 38 
title length, 83 
titles, 81 

. 11 (title) request, 85 
. t m (terminal message) request, 94 
. t r (translate characters) request, ISO 
translating characters, ISO 
transparent throughput, 10 
traps 

Change position of, 116 
diversion, 116 
end-of-processing, 117 
inputnline^count, 116 
page, 114 
trof f command 
exit firom, 94 
introduction to, 3,13 
turn escape mechanism on and off, 149 

u 

\u (move up) function, 131 

. u (hU mode indicator) nurriber register, 23 

. u f (underline font) request, 29 

. u 1 (underline) request, 28 

underline font request, 29 

underline request, 28 

units, 10 

unpaddable space, 17 

V 

\ V (vertical motion) function, 132 
. V (vertical spacing) number register, 51 
vertical lines, 143,144 
vertical motion, 132 
vertical position 
mark, 43 
return to, 44 

vertical spacing request, 51 
. vs (change vertical spacing) request, 51 

w 

\w (width) function, 140 
. wh (when request, 115, 82 

wh&n something request, 82,115 
width function, 140 
word, 17 


n 

X 

\x (get extra line space) function, 52 

Y 

y r (last two digits of year) number register, 121 

z 

\ z (zero motion) function, 139 
. z (name of current diversion) number register, 114 
zero motion function, 139 
zero-width character, 18, 137 
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